chadstart 1.0.0

package/core/entity-engine.js

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * Convert the raw YAML config into normalized internal models.
+ *
+ * Authenticable entities (user collections) are entities with
+ * `authenticable: true` — no separate userCollections section.
+ */
+
+const EMOJI_ACCESS = { '🌐': 'public', '🔒': 'restricted', '👨🏻‍💻': 'admin', '🚫': 'forbidden' };
+
+function normalizePolicies(raw) {
+  if (!raw) return {};
+  const out = {};
+  for (const [rule, list] of Object.entries(raw)) {
+    out[rule] = list.map((p) => ({
+      access: EMOJI_ACCESS[p.access] || p.access,
+      allow: p.allow || null,
+      condition: p.condition || null,
+    }));
+  }
+  return out;
+}
+
+function normalizeRelation(rel) {
+  if (typeof rel === 'string') return { name: rel, entity: rel };
+  return { name: rel.name || rel.entity, entity: rel.entity || rel.name, ...rel };
+}
+
+function normalizeProperty(prop) {
+  if (typeof prop === 'string') return { name: prop, type: 'string' };
+  return {
+    name: prop.name,
+    type: prop.type || 'string',
+    hidden: prop.hidden === true,
+    default: prop.default !== undefined ? prop.default : undefined,
+    options: prop.options || undefined,
+    helpText: prop.helpText || undefined,
+    validation: prop.validation || undefined,
+  };
+}
+
+function buildEntities(config) {
+  const entities = {};
+
+  for (const [name, def] of Object.entries(config.entities || {})) {
+    const properties = (def.properties || []).map(normalizeProperty);
+
+    // Merge inline property validation into entity-level validation.
+    // Inline declarations prevail over block-level on conflict.
+    const validation = { ...(def.validation || {}) };
+    for (const p of properties) {
+      if (p.validation) {
+        validation[p.name] = { ...(validation[p.name] || {}), ...p.validation };
+      }
+    }
+
+    entities[name] = {
+      name,
+      tableName: toSnakeCase(name),
+      slug: def.slug || toKebabCase(name),
+      authenticable: def.authenticable === true,
+      single: def.single === true,
+      mainProp: def.mainProp || null,
+      nameSingular: def.nameSingular || null,
+      namePlural: def.namePlural || null,
+      seedCount: def.seedCount || 50,
+      properties,
+      belongsTo: (def.belongsTo || []).map(normalizeRelation),
+      belongsToMany: (def.belongsToMany || []).map(normalizeRelation),
+      policies: normalizePolicies(def.policies),
+      validation,
+      hooks: def.hooks || {},
+      middlewares: def.middlewares || {},
+    };
+  }
+
+  return entities;
+}
+
+function getAuthenticableEntities(entities) {
+  return Object.fromEntries(
+    Object.entries(entities).filter(([, e]) => e.authenticable)
+  );
+}
+
+function toSnakeCase(str) {
+  return str.replace(/([A-Z])/g, (m, p, o) => (o > 0 ? '_' : '') + p.toLowerCase()).replace(/^_/, '');
+}
+
+function toKebabCase(str) {
+  return str.replace(/([A-Z])/g, (m, p, o) => (o > 0 ? '-' : '') + p.toLowerCase()).replace(/^-/, '');
+}
+
+/** Default Admin entity definition — email + password authenticable entity. */
+const DEFAULT_ADMIN_ENTITY = {
+  authenticable: true,
+  mainProp: 'email',
+  properties: [],
+};
+
+/**
+ * Build the Admin entity for the built-in admin access.
+ * Always included unless admin.enable_entity is explicitly false.
+ * If the user defines an "Admin" entity in their YAML, it is merged with the default.
+ */
+function buildAdminEntity(config) {
+  const adminCfg = config.admin || {};
+  if (adminCfg.enable_entity === false) return null;
+
+  const userDef = (config.entities || {}).Admin || {};
+  const merged = {
+    ...DEFAULT_ADMIN_ENTITY,
+    ...userDef,
+    // Always authenticable
+    authenticable: true,
+    // Merge properties: user-defined takes precedence (email/password are handled by auth system)
+    properties: userDef.properties || DEFAULT_ADMIN_ENTITY.properties,
+  };
+  return merged;
+}
+
+function buildCore(config) {
+  const adminCfg = config.admin || {};
+
+  // Inject the default Admin entity into entities map before building
+  const rawEntities = { ...(config.entities || {}) };
+  const adminEntityDef = buildAdminEntity(config);
+  if (adminEntityDef && !rawEntities.Admin) {
+    rawEntities.Admin = adminEntityDef;
+  } else if (adminEntityDef && rawEntities.Admin) {
+    // Merge: user-defined fields override defaults, but authenticable is always true
+    rawEntities.Admin = {
+      ...DEFAULT_ADMIN_ENTITY,
+      ...rawEntities.Admin,
+      authenticable: true,
+    };
+  }
+
+  const entities = buildEntities({ ...config, entities: rawEntities });
+
+  const rateLimits = config.rateLimits || null;
+  const telemetry = config.telemetry || null;
+
+  return {
+    name: config.name,
+    database: config.database || null,
+    entities,
+    authenticableEntities: getAuthenticableEntities(entities),
+    functions: config.functions || {},
+    groups: config.groups || {},
+    plugins: config.plugins || [],
+    files: config.files || {},
+    public: config.public || null,
+    port: parseInt(process.env.CHADSTART_PORT || process.env.PORT || config.port || 3000, 10),
+    rateLimits,
+    telemetry,
+    admin: {
+      enable_app: adminCfg.enable_app !== false,
+      enable_entity: adminCfg.enable_entity !== false,
+      policies: adminCfg.policies || [{ access: 'admin' }],
+    },
+  };
+}
+
+module.exports = { buildCore, buildEntities, getAuthenticableEntities, toSnakeCase, toKebabCase };

package/core/error-reporter.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * Error Reporting integration for ChadStart.
+ *
+ * Supports Sentry (https://sentry.io) for automatic exception tracking.
+ * To enable, set the SENTRY_DSN environment variable — it is treated as a
+ * secret and must NOT be placed in the YAML config file.
+ *
+ * Non-sensitive settings (environment label, sample rates) can be provided
+ * via the `sentry` section of your chadstart.yaml or via environment variables.
+ *
+ * 💡 Self-hosted alternative: Bugsink (https://www.bugsink.com) is a
+ *    lightweight, privacy-first alternative to Sentry that is fully
+ *    compatible with the Sentry SDK.  Simply point SENTRY_DSN at your
+ *    Bugsink instance — no other code changes required.
+ *
+ * Example chadstart.yaml:
+ *   sentry:
+ *     environment: production    # optional (defaults to NODE_ENV)
+ *     tracesSampleRate: 0.2      # optional (default: 1.0)
+ *     debug: false               # optional (default: false)
+ *
+ * Example .env:
+ *   SENTRY_DSN=https://xxxxx@oXXXXX.ingest.sentry.io/XXXXXXX
+ */
+
+const logger = require('../utils/logger');
+
+let _sentry = null;
+let _initialized = false;
+
+/**
+ * Initialise the Sentry SDK if SENTRY_DSN is set.
+ *
+ * @param {object} core  The parsed chadstart config (core object).
+ */
+function initErrorReporter(core) {
+  const dsn = process.env.SENTRY_DSN;
+  if (!dsn) return;
+
+  /* istanbul ignore next */
+  try {
+    _sentry = require('@sentry/node');
+  } catch {
+    logger.warn('[error-reporter] SENTRY_DSN is set but @sentry/node is not installed. Run: npm install @sentry/node');
+    return;
+  }
+
+  const sentryConfig = (core && core.sentry) || {};
+
+  _sentry.init({
+    dsn,
+    environment: sentryConfig.environment || process.env.NODE_ENV || 'development',
+    tracesSampleRate: sentryConfig.tracesSampleRate !== undefined
+      ? sentryConfig.tracesSampleRate
+      : 1.0,
+    debug: sentryConfig.debug === true,
+  });
+
+  _initialized = true;
+  logger.info('[error-reporter] Error reporting enabled via Sentry');
+}
+
+/**
+ * Returns the Sentry Express request handler middleware, or null when Sentry
+ * is not configured.  Must be added as the *first* middleware in the chain.
+ *
+ * @returns {import('express').RequestHandler|null}
+ */
+function getRequestHandler() {
+  if (!_initialized || !_sentry) return null;
+  return _sentry.expressIntegration
+    ? null                            // v8+: request capture is automatic
+    : _sentry.Handlers.requestHandler();
+}
+
+/**
+ * Returns the Sentry Express error handler middleware, or null when Sentry
+ * is not configured.  Must be added *after* all routes and before any other
+ * error-handling middleware.
+ *
+ * For Sentry v8+, use `attachErrorHandler(app)` instead — this function
+ * returns null for v8 since error handling is registered via
+ * `setupExpressErrorHandler`.
+ *
+ * @returns {import('express').ErrorRequestHandler|null}
+ */
+function getErrorHandler() {
+  if (!_initialized || !_sentry) return null;
+  // v8+ registers error handling differently via setupExpressErrorHandler;
+  // use attachErrorHandler(app) for v8.
+  if (typeof _sentry.setupExpressErrorHandler === 'function') return null;
+  /* istanbul ignore next */
+  return _sentry.Handlers.errorHandler();
+}
+
+/**
+ * Attach Sentry error-handler middleware to an Express app (v8 compatible).
+ * Call this after registering all routes.
+ *
+ * @param {import('express').Application} app
+ */
+function attachErrorHandler(app) {
+  if (!_initialized || !_sentry) return;
+  if (typeof _sentry.setupExpressErrorHandler === 'function') {
+    _sentry.setupExpressErrorHandler(app);
+  } else {
+    /* istanbul ignore next */
+    app.use(_sentry.Handlers.errorHandler());
+  }
+}
+
+/** Expose the initialised Sentry instance (useful for manual captures). */
+function getSentry() {
+  return _initialized ? _sentry : null;
+}
+
+/** Reset state (used in tests). */
+function _reset() {
+  _sentry = null;
+  _initialized = false;
+}
+
+module.exports = {
+  initErrorReporter,
+  getRequestHandler,
+  getErrorHandler,
+  attachErrorHandler,
+  getSentry,
+  _reset,
+};

package/core/file-storage.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const express = require('express');
+const logger = require('../utils/logger');
+
+/**
+ * Register file storage routes for all buckets defined in core.files.
+ * Each bucket exposes:
+ *   POST   /files/<bucket>          — upload (multipart/form-data, field name "file")
+ *   GET    /files/<bucket>/:file    — download
+ */
+function registerFileRoutes(app, core) {
+  const cwd = process.cwd();
+
+  for (const [bucketName, bucketDef] of Object.entries(core.files)) {
+    const bucketPath = path.resolve(bucketDef.path);
+
+    // Validate that the bucket path stays within the working directory
+    if (!bucketPath.startsWith(cwd + path.sep) && bucketPath !== cwd) {
+      throw new Error(
+        `File bucket "${bucketName}" path "${bucketDef.path}" resolves outside the working directory.`
+      );
+    }
+
+    // Ensure the upload directory exists
+    fs.mkdirSync(bucketPath, { recursive: true });
+
+    // Serve files statically if public
+    if (bucketDef.public !== false) {
+      app.use(`/files/${bucketName}`, express.static(bucketPath));
+    }
+
+    // Upload endpoint — uses raw multipart parsing via busboy
+    app.post(`/files/${bucketName}`, (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 Busboy = getBusboy();
+      const busboy = Busboy({ headers: req.headers });
+      let saved = false;
+      let savedName = null;
+
+      busboy.on('file', (fieldname, file, info) => {
+        const { filename } = info;
+        if (!filename) {
+          file.resume();
+          return;
+        }
+        // Sanitize filename — strip directory traversal and disallow problematic characters
+        const safeName = path
+          .basename(filename)
+          .replace(/[^a-zA-Z0-9._-]/g, '_')
+          .replace(/^\.+/, '_');
+        const dest = path.join(bucketPath, safeName);
+        const writeStream = fs.createWriteStream(dest);
+        file.pipe(writeStream);
+        writeStream.on('finish', () => {
+          saved = true;
+          savedName = safeName;
+        });
+      });
+
+      busboy.on('finish', () => {
+        if (saved) {
+          res.json({ file: savedName, url: `/files/${bucketName}/${savedName}` });
+        } else {
+          res.status(400).json({ error: 'No file field found in upload' });
+        }
+      });
+
+      busboy.on('error', (err) => {
+        logger.error('Upload error', err.message);
+        res.status(500).json({ error: err.message });
+      });
+
+      req.pipe(busboy);
+    });
+
+    logger.info(`  Registered file bucket "${bucketName}" at /files/${bucketName} -> ${bucketPath}`);
+  }
+}
+
+function getBusboy() {
+  try {
+    return require('busboy');
+  } catch {
+    throw new Error(
+      'busboy is required for file uploads. Install it with: npm install busboy'
+    );
+  }
+}
+
+module.exports = { registerFileRoutes };