chadstart 1.0.0

package/core/realtime.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { WebSocketServer } = require('ws');
+const logger = require('../utils/logger');
+
+let wss = null;
+// Map of channel -> Set of WebSocket clients
+const subscriptions = new Map();
+
+/**
+ * Attach a WebSocket server to an existing HTTP server.
+ * Clients connect and send JSON messages to subscribe to channels.
+ *
+ * Subscribe message format:
+ *   { "type": "subscribe", "channel": "Post" }
+ *
+ * Event message format (server → client):
+ *   { "type": "event", "event": "Post.created", "data": { ... } }
+ */
+function initRealtime(httpServer) {
+  wss = new WebSocketServer({ server: httpServer, path: '/realtime' });
+
+  wss.on('connection', (ws) => {
+    logger.debug('Realtime: new client connected');
+    const clientChannels = new Set();
+
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'subscribe' && msg.channel) {
+          subscribe(msg.channel, ws);
+          clientChannels.add(msg.channel);
+          ws.send(JSON.stringify({ type: 'subscribed', channel: msg.channel }));
+        } else if (msg.type === 'unsubscribe' && msg.channel) {
+          unsubscribe(msg.channel, ws);
+          clientChannels.delete(msg.channel);
+          ws.send(JSON.stringify({ type: 'unsubscribed', channel: msg.channel }));
+        }
+      } catch (err) {
+        logger.debug('Realtime: invalid message', err.message);
+      }
+    });
+
+    ws.on('close', () => {
+      for (const channel of clientChannels) {
+        unsubscribe(channel, ws);
+      }
+      logger.debug('Realtime: client disconnected');
+    });
+  });
+
+  logger.info('Realtime WebSocket server ready at /realtime');
+  return wss;
+}
+
+function subscribe(channel, ws) {
+  if (!subscriptions.has(channel)) {
+    subscriptions.set(channel, new Set());
+  }
+  subscriptions.get(channel).add(ws);
+}
+
+function unsubscribe(channel, ws) {
+  if (subscriptions.has(channel)) {
+    subscriptions.get(channel).delete(ws);
+  }
+}
+
+/**
+ * Emit an event to all subscribers of the entity channel.
+ * eventName format: "EntityName.created" | "EntityName.updated" | "EntityName.deleted"
+ */
+function emit(eventName, data) {
+  const entityName = eventName.split('.')[0];
+  const channels = [entityName, '*'];
+
+  for (const channel of channels) {
+    const clients = subscriptions.get(channel);
+    if (!clients) continue;
+    const payload = JSON.stringify({ type: 'event', event: eventName, data });
+    for (const ws of clients) {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(payload);
+      }
+    }
+  }
+}
+
+function getWss() {
+  return wss;
+}
+
+module.exports = { initRealtime, emit, subscribe, unsubscribe, getWss };

package/core/schema-validator.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const path = require('path');
+
+const schema = require(path.join(__dirname, '..', 'chadstart.schema.json'));
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+const validate = ajv.compile(schema);
+
+/**
+ * Format a single AJV error into a human-readable string, enriched with
+ * the relevant `params` data so the user knows exactly what went wrong.
+ *
+ * @param {import('ajv').ErrorObject} e
+ * @returns {string}
+ */
+function formatError(e) {
+  switch (e.keyword) {
+    case 'additionalProperties':
+      return `unknown property '${e.params.additionalProperty}'`;
+    case 'enum':
+      return `${e.message} (${e.params.allowedValues.join(', ')})`;
+    default:
+      return `${e.message}`;
+  }
+}
+
+/**
+ * Validate a parsed YAML config against the ChadStart JSON Schema.
+ * Throws a descriptive error on failure, returns true on success.
+ */
+function validateSchema(config) {
+  const valid = validate(config);
+  if (!valid) {
+    // oneOf/anyOf errors are always redundant when allErrors:true already
+    // surfaces the specific sub-errors, so we drop them to reduce noise.
+    const errors = validate.errors.filter(
+      (e) => e.keyword !== 'oneOf' && e.keyword !== 'anyOf',
+    );
+    const messages = errors.map(formatError);
+    throw new Error(`Config validation failed:\n  ${messages.join('\n  ')}`);
+  }
+  return true;
+}
+
+module.exports = { validateSchema };

package/core/seeder.js

@@ -0,0 +1,231 @@
+'use strict';
+
+/**
+ * Seeder — generates dummy data for all entities defined in the YAML config.
+ * Each entity can set `seedCount` (default: 50) to control how many records
+ * are created per run.
+ */
+
+const bcrypt = require('bcryptjs');
+const { create, findAllSimple } = require('./db');
+const logger = require('../utils/logger');
+
+const ADMIN_EMAIL = 'admin@chadstart.com';
+const ADMIN_PASSWORD = 'admin';
+
+// ─── Dummy value generators ──────────────────────────────────────────────────
+
+const WORDS = [
+  'alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel',
+  'india', 'juliet', 'kilo', 'lima', 'mike', 'november', 'oscar', 'papa',
+  'quebec', 'romeo', 'sierra', 'tango', 'uniform', 'victor', 'whiskey',
+  'xray', 'yankee', 'zulu',
+];
+
+let _counter = 0;
+
+function nextId() {
+  return ++_counter;
+}
+
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+function randomWord() {
+  return WORDS[randomInt(0, WORDS.length - 1)];
+}
+
+function randomWords(count) {
+  return Array.from({ length: count }, randomWord).join(' ');
+}
+
+function fakeValueForProp(prop, idx, groups = {}) {
+  const { name, type, options } = prop;
+  const n = idx + 1;
+
+  if (options && Array.isArray(options) && options.length > 0) {
+    return options[randomInt(0, options.length - 1)];
+  }
+
+  switch (type) {
+    case 'string':
+      return `${name} ${n} ${randomWord()}`;
+    case 'text':
+    case 'richText':
+      return `${randomWords(4)} ${n}. ${randomWords(5)}.`;
+    case 'integer':
+    case 'int':
+      return randomInt(1, 1000);
+    case 'number':
+    case 'float':
+    case 'real':
+    case 'money':
+      return Math.round(randomInt(1, 10000) * 0.01 * 100) / 100;
+    case 'boolean':
+    case 'bool':
+      return randomInt(0, 1);
+    case 'date':
+      return new Date(Date.now() - randomInt(0, 365) * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .slice(0, 10);
+    case 'timestamp':
+      return new Date(Date.now() - randomInt(0, 365) * 24 * 60 * 60 * 1000).toISOString();
+    case 'email':
+      return `${randomWord()}${n}@example.com`;
+    case 'link':
+      return `https://example.com/${randomWord()}/${n}`;
+    case 'password':
+      return `password${n}`;
+    case 'choice':
+      return randomWord();
+    case 'location': {
+      const lat = (randomInt(-9000, 9000) / 100).toFixed(2);
+      const lng = (randomInt(-18000, 18000) / 100).toFixed(2);
+      return `${lat},${lng}`;
+    }
+    case 'file':
+    case 'image':
+      return `/uploads/placeholder-${n}.png`;
+    case 'json':
+      return JSON.stringify({ id: n, value: randomWord() });
+    case 'group': {
+      const groupName = options && options.group;
+      const groupDef = groups && groupName ? groups[groupName] : null;
+      if (groupDef && groupDef.properties) {
+        const multiple = !options || options.multiple !== false;
+        const count = multiple ? 2 : 1;
+        const items = Array.from({ length: count }, (_, j) =>
+          groupDef.properties.reduce((item, gp) => {
+            item[gp.name] = fakeValueForProp(gp, j, groups);
+            return item;
+          }, {})
+        );
+        return JSON.stringify(multiple ? items : items[0]);
+      }
+      return JSON.stringify([]);
+    }
+    default:
+      return `${name} ${n} ${randomWord()}`;
+  }
+}
+
+// ─── Topological sort ────────────────────────────────────────────────────────
+
+/**
+ * Sort entities so that parents always come before their dependents.
+ * This ensures belongsTo FK references can be resolved.
+ */
+function sortByDependency(entities) {
+  const names = Object.keys(entities);
+  const visited = new Set();
+  const sorted = [];
+
+  function visit(name) {
+    if (visited.has(name)) return;
+    visited.add(name);
+    const entity = entities[name];
+    for (const rel of entity.belongsTo || []) {
+      const parent = typeof rel === 'string' ? rel : (rel.entity || rel.name);
+      if (entities[parent]) visit(parent);
+    }
+    sorted.push(name);
+  }
+
+  for (const name of names) visit(name);
+  return sorted;
+}
+
+// ─── Main seed function ──────────────────────────────────────────────────────
+
+/**
+ * Seed all entities in `core`.
+ * Returns a summary map: { EntityName: count }.
+ */
+async function seedAll(core) {
+  _counter = 0;
+  const runToken = `${Date.now().toString(36)}${randomInt(1000, 9999)}`;
+  const sortedNames = sortByDependency(core.entities);
+  const summary = {};
+
+  // Track seeded ids per entity for FK resolution
+  const seededIds = {};
+
+  for (const entityName of sortedNames) {
+    const entity = core.entities[entityName];
+
+    // Singles are singleton records — only seed once if table is empty.
+    // We still respect seedCount=1 implicitly.
+    const count = entity.single ? 1 : (entity.seedCount || 50);
+
+    const ids = [];
+
+    for (let i = 0; i < count; i++) {
+      const record = {};
+
+      // Authenticable entities need email + (hashed) password
+      if (entity.authenticable) {
+        const n = nextId();
+        record.email = `${entityName.toLowerCase()}-${runToken}-${n}@example.com`;
+        record.password = bcrypt.hashSync(`password${n}`, 10);
+      }
+
+      // Regular properties (skip email/password for authenticable entities — handled above)
+      for (const prop of entity.properties) {
+        if (entity.authenticable && (prop.name === 'email' || prop.name === 'password')) continue;
+        if (prop.type === 'password') {
+          record[prop.name] = bcrypt.hashSync(fakeValueForProp(prop, i, core.groups), 10);
+        } else {
+          record[prop.name] = fakeValueForProp(prop, i, core.groups);
+        }
+      }
+
+      // BelongsTo FK: pick a random seeded parent id
+      for (const rel of entity.belongsTo || []) {
+        const parentName = typeof rel === 'string' ? rel : (rel.entity || rel.name);
+        const parentEntity = core.entities[parentName];
+        if (parentEntity && seededIds[parentName] && seededIds[parentName].length > 0) {
+          const fk = `${parentEntity.tableName}_id`;
+          const parentIds = seededIds[parentName];
+          record[fk] = parentIds[randomInt(0, parentIds.length - 1)];
+        }
+      }
+
+      try {
+        const created = create(entity.tableName, record);
+        ids.push(created.id);
+      } catch (err) {
+        logger.warn(`Seed: failed to create record for ${entityName}:`, err.message);
+      }
+    }
+
+    seededIds[entityName] = ids;
+    summary[entityName] = ids.length;
+  }
+
+  // Create the admin@chadstart.com user in every authenticable entity
+  const adminUsers = [];
+  for (const entity of Object.values(core.authenticableEntities || {})) {
+    const existing = findAllSimple(entity.tableName, { email: ADMIN_EMAIL });
+    if (existing.length === 0) {
+      const extraProps = entity.properties.reduce((acc, prop) => {
+        // Skip email and password — they are handled separately for authenticable entities
+        if (prop.name === 'email' || prop.name === 'password') return acc;
+        if (prop.type !== 'password') {
+          acc[prop.name] = fakeValueForProp(prop, 0, core.groups);
+        }
+        return acc;
+      }, {});
+      create(entity.tableName, {
+        email: ADMIN_EMAIL,
+        password: bcrypt.hashSync(ADMIN_PASSWORD, 10),
+        ...extraProps,
+      });
+      adminUsers.push(entity.name);
+    }
+  }
+
+  return { summary, adminEmail: ADMIN_EMAIL, adminPassword: ADMIN_PASSWORD, adminEntities: adminUsers };
+}
+
+module.exports = { seedAll, ADMIN_EMAIL, ADMIN_PASSWORD };

package/core/telemetry.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * OpenTelemetry integration for ChadStart.
+ *
+ * Non-secret values (service name, endpoint URL) can be configured via
+ * the YAML settings block or environment variables.
+ *
+ * Secret values (OTLP auth headers / API keys) MUST be provided via
+ * environment variables only — never put secrets in the YAML config file.
+ *
+ * Environment variables (all override YAML):
+ *   OTEL_ENABLED=true                         enable tracing
+ *   OTEL_SERVICE_NAME=my-service              service name reported to the collector
+ *   OTEL_EXPORTER_OTLP_ENDPOINT=http://...    OTLP collector base URL
+ *   OTEL_EXPORTER_OTLP_HEADERS=k1=v1,k2=v2   auth headers (secrets – env var only)
+ */
+
+const logger = require('../utils/logger');
+
+/** @type {import('@opentelemetry/sdk-node').NodeSDK | null} */
+let _sdk = null;
+
+/**
+ * Parse OTLP headers from the env-var format: "key1=value1,key2=value2".
+ *
+ * @param {string} raw
+ * @returns {Record<string, string>}
+ */
+function parseOtlpHeaders(raw) {
+  const headers = {};
+  for (const pair of raw.split(',')) {
+    const idx = pair.indexOf('=');
+    if (idx > 0) {
+      headers[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+    }
+  }
+  return headers;
+}
+
+/**
+ * Derive telemetry configuration from YAML telemetry config + environment variables.
+ * Returns null when telemetry is disabled.
+ *
+ * @param {object|null} telemetry  Value of `core.telemetry` (may be null)
+ * @returns {{ enabled: true, serviceName: string, endpoint: string, headers: Record<string,string> } | null}
+ */
+function getTelemetryConfig(telemetry) {
+  const tel = telemetry || {};
+
+  const enabled =
+    process.env.OTEL_ENABLED === 'true' ||
+    tel.enabled === true;
+
+  if (!enabled) return null;
+
+  return {
+    enabled: true,
+    serviceName: process.env.OTEL_SERVICE_NAME || tel.serviceName || 'chadstart-app',
+    endpoint:    process.env.OTEL_EXPORTER_OTLP_ENDPOINT || tel.endpoint || 'http://localhost:4318',
+    // Headers carry secrets (API keys, bearer tokens) — only accepted from env var.
+    headers: process.env.OTEL_EXPORTER_OTLP_HEADERS
+      ? parseOtlpHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS)
+      : {},
+  };
+}
+
+/**
+ * Initialize the OpenTelemetry Node SDK with OTLP HTTP export.
+ * This is a singleton — subsequent calls are no-ops (safe to call on hot reload).
+ *
+ * @param {{ enabled: true, serviceName: string, endpoint: string, headers: object } | null} telConfig
+ */
+async function initTelemetry(telConfig) {
+  if (!telConfig || !telConfig.enabled) return;
+  if (_sdk) return; // Already initialized — no-op on hot reload
+
+  try {
+    const { NodeSDK } = require('@opentelemetry/sdk-node');
+    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+    const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+    const { resourceFromAttributes } = require('@opentelemetry/resources');
+    const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
+
+    const exporter = new OTLPTraceExporter({
+      url: `${telConfig.endpoint}/v1/traces`,
+      headers: telConfig.headers,
+    });
+
+    _sdk = new NodeSDK({
+      resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: telConfig.serviceName }),
+      traceExporter: exporter,
+      instrumentations: [getNodeAutoInstrumentations()],
+    });
+
+    _sdk.start();
+    logger.info(`  OpenTelemetry tracing enabled (service: ${telConfig.serviceName}, endpoint: ${telConfig.endpoint})`);
+  } catch (err) {
+    logger.error('Failed to initialize OpenTelemetry:', err.message);
+  }
+}
+
+/**
+ * Gracefully flush pending spans and shut down the SDK.
+ * Resets the singleton so a fresh `initTelemetry` call can re-initialize.
+ */
+async function shutdownTelemetry() {
+  if (_sdk) {
+    try {
+      await _sdk.shutdown();
+    } catch (err) {
+      logger.error('Failed to shut down OpenTelemetry:', err.message);
+    } finally {
+      _sdk = null;
+    }
+  }
+}
+
+module.exports = { getTelemetryConfig, initTelemetry, shutdownTelemetry, parseOtlpHeaders };