chadstart 1.0.0

package/core/upload.js

@@ -0,0 +1,372 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const logger = require('../utils/logger');
+
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** Returns a month folder string like "Mar2026". */
+function getMonthFolder(date) {
+  const d = date || new Date();
+  return `${MONTH_NAMES[d.getMonth()]}${d.getFullYear()}`;
+}
+
+/** Returns the configured base URL (defaults to http://localhost:<port>). */
+function getBaseUrl(core) {
+  return process.env.BASE_URL || `http://localhost:${core.port}`;
+}
+
+/** Returns true when all required S3 env vars are set. */
+function isS3Configured() {
+  return !!(
+    process.env.S3_BUCKET &&
+    process.env.S3_ENDPOINT &&
+    process.env.S3_REGION &&
+    process.env.S3_ACCESS_KEY_ID &&
+    process.env.S3_SECRET_ACCESS_KEY
+  );
+}
+
+/** Sanitizes a filename to prevent path traversal and special chars. */
+function sanitizeFilename(filename) {
+  return path.basename(filename)
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .replace(/^\.+/, '_');
+}
+
+/** Generates a short random unique prefix for filenames. */
+function generateUniquePrefix() {
+  return (
+    Math.random().toString(36).slice(2, 10) +
+    Math.random().toString(36).slice(2, 10)
+  );
+}
+
+/** Saves a buffer to a local directory and returns the full file path. */
+function saveLocally(buffer, dir, filename) {
+  fs.mkdirSync(dir, { recursive: true });
+  const dest = path.join(dir, filename);
+  fs.writeFileSync(dest, buffer);
+  return dest;
+}
+
+/**
+ * Uploads a buffer to S3 and returns the public URL.
+ * The path is optionally prefixed by S3_FOLDER_PREFIX.
+ */
+async function uploadToS3(buffer, key, contentType) {
+  const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
+  const folderPrefix = process.env.S3_FOLDER_PREFIX
+    ? `${process.env.S3_FOLDER_PREFIX}/`
+    : '';
+  const fullKey = `${folderPrefix}${key}`;
+
+  const client = new S3Client({
+    region: process.env.S3_REGION,
+    endpoint: process.env.S3_ENDPOINT,
+    credentials: {
+      accessKeyId: process.env.S3_ACCESS_KEY_ID,
+      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+    },
+    forcePathStyle: true,
+  });
+
+  await client.send(
+    new PutObjectCommand({
+      Bucket: process.env.S3_BUCKET,
+      Key: fullKey,
+      Body: buffer,
+      ContentType: contentType,
+    })
+  );
+
+  return `${process.env.S3_ENDPOINT}/${process.env.S3_BUCKET}/${fullKey}`;
+}
+
+/**
+ * Returns image processing options for the given entity + property.
+ *
+ * Defaults:
+ *   - compress: true  (convert to JPEG at quality 80; disable with `options.compress: false`)
+ *   - quality:  80    (JPEG quality 1-100; override with `options.quality`)
+ *   - sizes:    null  (no resizing; enable with `options.sizes: { name: [w, h], ... }`)
+ */
+function getImageOptions(core, entity, property) {
+  const entityDef = Object.values(core.entities || {}).find(
+    (e) =>
+      e.slug === entity ||
+      e.tableName === entity ||
+      e.name === entity
+  );
+  const propDef = entityDef && entityDef.properties.find((p) => p.name === property);
+  const opts = (propDef && propDef.options) || {};
+
+  return {
+    compress: opts.compress !== false,
+    quality:  typeof opts.quality === 'number' ? opts.quality : 80,
+    sizes:    opts.sizes || null,
+  };
+}
+
+/**
+ * Register upload routes:
+ *   POST /api/upload/file   — upload any file
+ *   POST /api/upload/image  — upload + resize a PNG/JPG image
+ */
+function registerUploadRoutes(app, core) {
+  const Busboy = getBusboy();
+
+  // ── POST /api/upload/file ───────────────────────────────────────────────────
+  app.post('/api/upload/file', (req, res) => {
+    const contentType = req.headers['content-type'] || '';
+    if (!contentType.includes('multipart/form-data')) {
+      return res.status(400).json({ error: 'Expected multipart/form-data' });
+    }
+
+    const bb = Busboy({ headers: req.headers });
+    const fields = {};
+    let fileBuffer = null;
+    let fileInfo = null;
+
+    bb.on('field', (name, value) => {
+      fields[name] = value;
+    });
+
+    bb.on('file', (_fieldname, stream, info) => {
+      const chunks = [];
+      stream.on('data', (chunk) => chunks.push(chunk));
+      stream.on('end', () => {
+        fileBuffer = Buffer.concat(chunks);
+        fileInfo = info;
+      });
+    });
+
+    bb.on('finish', async () => {
+      try {
+        if (!fileBuffer || !fileInfo || !fileInfo.filename) {
+          return res.status(400).json({ error: 'No file provided' });
+        }
+
+        const { entity, property } = fields;
+        if (!entity || !property) {
+          return res.status(400).json({ error: 'Missing entity or property fields' });
+        }
+
+        const safeName = sanitizeFilename(fileInfo.filename);
+        const prefix = generateUniquePrefix();
+        const finalName = `${prefix}-${safeName}`;
+        const monthFolder = getMonthFolder();
+        const relPath = `storage/${entity}/${property}/${monthFolder}/${finalName}`;
+
+        let url;
+        if (isS3Configured()) {
+          url = await uploadToS3(
+            fileBuffer,
+            relPath,
+            fileInfo.mimeType || 'application/octet-stream'
+          );
+        } else {
+          const publicFolder = (core.public && core.public.folder) || './public';
+          const dir = path.resolve(
+            publicFolder,
+            'storage',
+            entity,
+            property,
+            monthFolder
+          );
+          saveLocally(fileBuffer, dir, finalName);
+          url = `${getBaseUrl(core)}/storage/${entity}/${property}/${monthFolder}/${finalName}`;
+        }
+
+        res.json({ path: url });
+      } catch (err) {
+        logger.error('File upload error', err.message);
+        res.status(500).json({ error: err.message });
+      }
+    });
+
+    bb.on('error', (err) => {
+      logger.error('Upload parse error', err.message);
+      res.status(500).json({ error: err.message });
+    });
+
+    req.pipe(bb);
+  });
+
+  // ── POST /api/upload/image ──────────────────────────────────────────────────
+  app.post('/api/upload/image', (req, res) => {
+    const contentType = req.headers['content-type'] || '';
+    if (!contentType.includes('multipart/form-data')) {
+      return res.status(400).json({ error: 'Expected multipart/form-data' });
+    }
+
+    const bb = Busboy({ headers: req.headers });
+    const fields = {};
+    let imageBuffer = null;
+    let imageInfo = null;
+
+    bb.on('field', (name, value) => {
+      fields[name] = value;
+    });
+
+    bb.on('file', (_fieldname, stream, info) => {
+      const chunks = [];
+      stream.on('data', (chunk) => chunks.push(chunk));
+      stream.on('end', () => {
+        imageBuffer = Buffer.concat(chunks);
+        imageInfo = info;
+      });
+    });
+
+    bb.on('finish', async () => {
+      try {
+        if (!imageBuffer || !imageInfo || !imageInfo.filename) {
+          return res.status(400).json({ error: 'No image provided' });
+        }
+
+        // Validate PNG/JPG only
+        const mime = (imageInfo.mimeType || '').toLowerCase();
+        const ext = path.extname(imageInfo.filename).toLowerCase();
+        const validMime = mime === 'image/png' || mime === 'image/jpeg';
+        const validExt = ext === '.png' || ext === '.jpg' || ext === '.jpeg';
+        if (!validMime && !validExt) {
+          return res
+            .status(400)
+            .json({ error: 'Only PNG and JPG images are accepted' });
+        }
+
+        const { entity, property } = fields;
+        if (!entity || !property) {
+          return res
+            .status(400)
+            .json({ error: 'Missing entity or property fields' });
+        }
+
+        const { compress, quality, sizes } = getImageOptions(core, entity, property);
+        const prefix = generateUniquePrefix();
+        const monthFolder = getMonthFolder();
+        const sharp = getSharp();
+
+        if (sizes) {
+          // ── Resize mode: one output file per configured size ──────────────────
+          const result = {};
+
+          for (const [sizeName, dims] of Object.entries(sizes)) {
+            const [width, height] = dims;
+            const filename = `${prefix}-${sizeName}.jpg`;
+            let pipeline = sharp(imageBuffer).resize(width, height, { fit: 'cover' });
+            pipeline = compress
+              ? pipeline.jpeg({ quality })
+              : pipeline.jpeg({ quality: 100 });
+            const processed = await pipeline.toBuffer();
+
+            if (isS3Configured()) {
+              const key = `storage/${entity}/${property}/${monthFolder}/${filename}`;
+              result[sizeName] = await uploadToS3(processed, key, 'image/jpeg');
+            } else {
+              const publicFolder = (core.public && core.public.folder) || './public';
+              const dir = path.resolve(
+                publicFolder,
+                'storage',
+                entity,
+                property,
+                monthFolder
+              );
+              saveLocally(processed, dir, filename);
+              result[sizeName] =
+                `${getBaseUrl(core)}/storage/${entity}/${property}/${monthFolder}/${filename}`;
+            }
+          }
+
+          return res.json(result);
+        }
+
+        // ── No-resize mode: single output file ───────────────────────────────
+        let processedBuffer;
+        let outputMime;
+        let finalName;
+
+        if (compress) {
+          // Convert to JPEG with lossy compression
+          processedBuffer = await sharp(imageBuffer).jpeg({ quality }).toBuffer();
+          outputMime = 'image/jpeg';
+          const baseName = path.basename(
+            sanitizeFilename(imageInfo.filename),
+            path.extname(imageInfo.filename)
+          );
+          finalName = `${prefix}-${baseName}.jpg`;
+        } else {
+          // Keep original bytes untouched
+          processedBuffer = imageBuffer;
+          outputMime = imageInfo.mimeType || 'image/octet-stream';
+          finalName = `${prefix}-${sanitizeFilename(imageInfo.filename)}`;
+        }
+
+        let url;
+        if (isS3Configured()) {
+          const key = `storage/${entity}/${property}/${monthFolder}/${finalName}`;
+          url = await uploadToS3(processedBuffer, key, outputMime);
+        } else {
+          const publicFolder = (core.public && core.public.folder) || './public';
+          const dir = path.resolve(
+            publicFolder,
+            'storage',
+            entity,
+            property,
+            monthFolder
+          );
+          saveLocally(processedBuffer, dir, finalName);
+          url = `${getBaseUrl(core)}/storage/${entity}/${property}/${monthFolder}/${finalName}`;
+        }
+
+        res.json({ path: url });
+      } catch (err) {
+        logger.error('Image upload error', err.message);
+        res.status(500).json({ error: err.message });
+      }
+    });
+
+    bb.on('error', (err) => {
+      logger.error('Upload parse error', err.message);
+      res.status(500).json({ error: err.message });
+    });
+
+    req.pipe(bb);
+  });
+
+  logger.info(
+    '  Registered upload routes at /api/upload/file and /api/upload/image'
+  );
+}
+
+function getBusboy() {
+  try {
+    return require('busboy');
+  } catch {
+    throw new Error(
+      'busboy is required for file uploads. Install it with: npm install busboy'
+    );
+  }
+}
+
+function getSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error(
+      'sharp is required for image uploads. Install it with: npm install sharp'
+    );
+  }
+}
+
+module.exports = {
+  registerUploadRoutes,
+  getBaseUrl,
+  getMonthFolder,
+  isS3Configured,
+  sanitizeFilename,
+  generateUniquePrefix,
+  saveLocally,
+  getImageOptions,
+};

package/core/workers/php_worker.php

@@ -0,0 +1,19 @@
+<?php
+// ChadStart PHP runtime worker.
+// Protocol: {"id": N, "entry": "/path/to/fn.php", "event": {...}, "ctx": {...}}
+
+while (($line = fgets(STDIN)) !== false) {
+    $line = trim($line);
+    if ($line === '') continue;
+    $req = json_decode($line, true);
+    try {
+        require_once $req['entry'];
+        $event = $req['event'] ?? [];
+        $ctx   = $req['ctx']   ?? [];
+        $result = function_exists('handler') ? handler($event, $ctx) : null;
+        echo json_encode(['id' => $req['id'], 'result' => $result]) . "\n";
+    } catch (Throwable $e) {
+        echo json_encode(['id' => $req['id'], 'error' => $e->getMessage()]) . "\n";
+    }
+    fflush(STDOUT);
+}

package/core/workers/python_worker.py

@@ -0,0 +1,33 @@
+"""
+ChadStart Python runtime worker.
+Reads newline-delimited JSON requests from stdin, invokes the function, writes JSON result to stdout.
+Protocol: {"id": N, "entry": "/path/to/fn.py", "event": {...}, "ctx": {...}}
+Response: {"id": N, "result": ...} or {"id": N, "error": "message"}
+"""
+import sys, json, importlib.util, asyncio, os
+
+def load_module(entry):
+    spec = importlib.util.spec_from_file_location("fn", entry)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+def run(mod, event, ctx):
+    fn = getattr(mod, 'handler', None) or getattr(mod, 'default', None)
+    if fn is None:
+        raise RuntimeError("No handler or default export found")
+    if asyncio.iscoroutinefunction(fn):
+        return asyncio.run(fn(event, ctx))
+    return fn(event, ctx)
+
+for line in sys.stdin:
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        req = json.loads(line)
+        mod = load_module(req["entry"])
+        result = run(mod, req.get("event", {}), req.get("ctx", {}))
+        print(json.dumps({"id": req["id"], "result": result}), flush=True)
+    except Exception as e:
+        print(json.dumps({"id": req.get("id"), "error": str(e)}), flush=True)

package/core/workers/ruby_worker.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# ChadStart Ruby runtime worker.
+# Protocol: {"id": N, "entry": "/path/to/fn.rb", "event": {...}, "ctx": {...}}
+require 'json'
+
+$stdout.sync = true
+
+$stdin.each_line do |line|
+  line.strip!
+  next if line.empty?
+  begin
+    req = JSON.parse(line)
+    load req['entry']
+    event = req['event'] || {}
+    ctx   = req['ctx']   || {}
+    result = defined?(handler) ? handler(event, ctx) : (defined?(default) ? method(:default).call(event, ctx) : nil)
+    puts JSON.generate({ id: req['id'], result: result })
+  rescue => e
+    puts JSON.generate({ id: req['id'], error: e.message })
+  end
+end

package/core/yaml-loader.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const YAML = require('yaml');
+const logger = require('../utils/logger');
+
+/**
+ * Load and parse the chadstart.yaml file.
+ * Returns the raw parsed object.
+ */
+function loadYaml(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`YAML config not found: ${resolved}`);
+  }
+  const raw = fs.readFileSync(resolved, 'utf8');
+  const parsed = YAML.parse(raw);
+  logger.debug('Loaded YAML from', resolved);
+  return parsed;
+}
+
+/**
+ * Save an updated config object back to a YAML file.
+ * Uses yaml's Document API so that comments in unchanged top-level sections
+ * are preserved as much as possible.
+ *
+ * @param {string} filePath  Path to the YAML file.
+ * @param {object} config    Plain-JS config object (already validated).
+ */
+function saveYaml(filePath, config) {
+  const resolved = path.resolve(filePath);
+
+  let doc;
+  if (fs.existsSync(resolved)) {
+    // Parse into a live Document to keep comments / blank lines on unchanged nodes
+    const raw = fs.readFileSync(resolved, 'utf8');
+    doc = YAML.parseDocument(raw);
+
+    const existing = doc.toJS() || {};
+    const existingKeys = Object.keys(existing);
+    const newKeys = Object.keys(config);
+
+    // Update or add every key from the incoming config
+    for (const key of newKeys) {
+      doc.set(key, config[key]);
+    }
+
+    // Remove top-level keys that are no longer present
+    for (const key of existingKeys) {
+      if (!newKeys.includes(key)) {
+        doc.delete(key);
+      }
+    }
+  } else {
+    // Create a fresh Document when the file does not yet exist
+    doc = new YAML.Document(config);
+  }
+
+  fs.writeFileSync(resolved, doc.toString(), 'utf8');
+  logger.debug('Saved YAML to', resolved);
+}
+
+module.exports = { loadYaml, saveYaml };

package/demo/chadstart.yaml

@@ -0,0 +1,178 @@
+# demo/chadstart.yaml
+# ─────────────────────────────────────────────────────────────────────────────
+# ChadStart Todo App — demonstration of a complete chadstart.yaml config.
+# Shows: entities, access policies, realtime, CRUD, and functions in every
+# supported runtime (js, bash, python, go, ruby, c++).
+#
+# To run locally:
+#   cd demo
+#   CHADSTART_CONFIG=./chadstart.yaml node ../index.js
+#
+# To run with Docker Compose:
+#   cd demo
+#   docker compose up --build
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: Todo App
+port: 3000
+database: ./data/todo.db
+
+entities:
+  User:
+    authenticable: true
+    mainProp: name
+    seedCount: 5
+    properties:
+      - name
+      - { name: email, type: email }
+      - { name: password, type: password }
+    policies:
+      create:
+        - access: public          # Anyone can sign up
+      read:
+        - access: restricted
+          allow: User
+          condition: self         # Users can only read their own profile
+      update:
+        - access: restricted
+          allow: User
+          condition: self
+      delete:
+        - access: admin
+      signup:
+        - access: public
+    validation:
+      name:
+        required: true
+        isNotEmpty: true
+        minLength: 2
+        maxLength: 100
+      email:
+        required: true
+        isEmail: true
+
+  Todo:
+    mainProp: title
+    seedCount: 20
+    belongsTo:
+      - User
+    properties:
+      - title
+      - { name: description, type: text }
+      - { name: completed,   type: boolean, default: false }
+      - { name: priority,    type: choice,  options: { values: [low, medium, high] } }
+      - { name: dueDate,     type: date }
+    policies:
+      create:
+        - { access: restricted, allow: User, condition: self }   # Set owner on create
+      read:
+        - { access: restricted, allow: User, condition: self }
+      update:
+        - { access: restricted, allow: User, condition: self }
+      delete:
+        - { access: restricted, allow: User, condition: self }
+    validation:
+      title:
+        required: true
+        isNotEmpty: true
+        maxLength: 255
+      priority:
+        isOptional: true
+        isIn: [low, medium, high]
+
+public:
+  folder: ./public
+
+functions:
+  # JS (default runtime) — returns per-status todo counts.
+  stats:
+    runtime: js
+    function: stats.js
+    description: Returns todo statistics (total, completed, pending).
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/stats
+        policies:
+          - access: public
+
+  # Bash — simple health/ping endpoint.
+  ping:
+    runtime: bash
+    function: ping.sh
+    description: Health check / ping — returns pong.
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/ping
+        policies:
+          - access: public
+      - type: cron
+        schedule: "@hourly"    # Log a heartbeat every hour
+
+  # Python — greets the caller by name.
+  greetPython:
+    runtime: python
+    function: hello.py
+    description: Returns a greeting from the Python runtime.
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/greet/python
+        policies:
+          - access: public
+
+  # Go — greets the caller from the Go runtime.
+  greetGo:
+    runtime: go
+    function: greet.go
+    description: Returns a greeting from the Go runtime.
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/greet/go
+        policies:
+          - access: public
+
+  # Ruby — greets the caller from the Ruby runtime.
+  greetRuby:
+    runtime: ruby
+    function: hello.rb
+    description: Returns a greeting from the Ruby runtime.
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/greet/ruby
+        policies:
+          - access: public
+
+  # C++ — greets the caller from the C++ runtime.
+  greetCpp:
+    runtime: c++
+    function: hello.cpp
+    description: Returns a greeting from the C++ runtime.
+    triggers:
+      - type: http
+        method: GET
+        path: /api/fn/greet/cpp
+        policies:
+          - access: public
+
+  # Event-driven — fires when a new todo is created (via the event bus).
+  onTodoCreated:
+    runtime: js
+    function: onTodoCreated.js
+    description: Runs after a new Todo is created (event trigger demo).
+    triggers:
+      - type: event
+        name: todo.created
+
+files:
+  uploads:
+    path: ./uploads
+    public: true
+
+rateLimits:
+  - name: default
+    limit: 200
+    ttl: 60000