chadstart 1.0.4 → 1.0.5

package/Dockerfile

@@ -9,7 +9,7 @@ RUN npm ci --omit=dev
 FROM node:lts-alpine AS runner
 WORKDIR /app
 # Runtime dependencies
-RUN apk add --no-cache bash python3 go ruby g++ \
+RUN apk add --no-cache bash python3 go ruby g++ jsonnet \
   && addgroup -S nodejs && adduser -S nodejs -G nodejs \
   && mkdir -p /app/{uploads,public,functions} && chown -R nodejs:nodejs /app
 COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules

package/admin/index.html

@@ -261,6 +261,7 @@
         <button onclick="showConfigTab('files')"     id="cfg-tab-files"     class="cfg-tab px-3 py-1.5 text-xs rounded border border-cs-border text-cs-muted hover:text-cs-text" style="transition:color 150ms,background 150ms;" data-i18n="config.tabs.files">Files &amp; Uploads</button>
         <button onclick="showConfigTab('settings')"  id="cfg-tab-settings"  class="cfg-tab px-3 py-1.5 text-xs rounded border border-cs-border text-cs-muted hover:text-cs-text" style="transition:color 150ms,background 150ms;" data-i18n="config.tabs.settings">Settings</button>
         <button onclick="showConfigTab('all')"       id="cfg-tab-all"       class="cfg-tab px-3 py-1.5 text-xs rounded border border-cs-border text-cs-muted hover:text-cs-text" style="transition:color 150ms,background 150ms;" data-i18n="config.tabs.all">All</button>
+        <span id="cfg-format-badge" class="ml-auto px-2 py-1 text-xs rounded font-mono" style="background:var(--color-cs-border);color:var(--color-cs-muted);" title="Config format">YAML</span>
       </div>
       <p id="cfg-section-desc" class="text-xs mb-3" style="color:var(--color-cs-muted);"></p>
       <div id="cfg-form" class="hidden mb-6"></div>
@@ -674,6 +675,8 @@
   // Config editor
   let configMode = false;
   let configData = null;
+  let configFormat = 'yaml';
+  let configWritable = true;
   let configActiveTab = 'general';
   let _cfgEntityId = 0, _cfgEndpointId = 0, _cfgFileId = 0, _cfgRlId = 0, _cfgTriggerId = 0;
 
@@ -1706,13 +1709,36 @@ const _LBL    = 'block text-xs mb-1';
 
 async function loadConfig() {
   try {
-    const r = await apiFetch('/admin/config');
+    const [r, infoRes] = await Promise.all([
+      apiFetch('/admin/config'),
+      apiFetch('/admin/config-info'),
+    ]);
     if (!r.ok) throw new Error('Failed to load config');
     configData = await r.json();
+    if (infoRes.ok) {
+      const info = await infoRes.json();
+      configFormat = info.format || 'yaml';
+      configWritable = info.writable !== false;
+    }
+    updateConfigFormatBadge();
     showConfigTab('general');
   } catch (e) { toast(e.message, 'error'); }
 }
 
+function updateConfigFormatBadge() {
+  const badge = document.getElementById('cfg-format-badge');
+  if (!badge) return;
+  badge.textContent = configFormat.toUpperCase();
+  badge.title = configWritable
+    ? 'Config format: ' + configFormat
+    : 'Config format: ' + configFormat + ' (read-only)';
+  const saveBtn = document.getElementById('cfg-save-btn');
+  if (saveBtn) {
+    saveBtn.disabled = !configWritable;
+    saveBtn.title = configWritable ? '' : 'Saving is not supported for ' + configFormat + ' configs. Convert to YAML, JSON, or JSON5 to enable saving.';
+  }
+}
+
 function showConfigTab(tab) {
   configActiveTab = tab;
   document.querySelectorAll('.cfg-tab').forEach(b => b.classList.remove('active'));

package/{chadstart.example.yml → chadstart.example.yaml}

@@ -1,4 +1,4 @@
-# chadstart.example.yml
+# chadstart.example.yaml
 # ─────────────────────────────────────────────────────────────────────────────
 # Reference file that lists every available option in a ChadStart YAML config.
 # Copy this file to chadstart.yaml and remove / adjust the sections you need.

package/cli/cli.js

@@ -7,23 +7,24 @@ const fs = require('fs');
 
 const args = process.argv.slice(2);
 const command = args[0];
-const DEFAULT_YAML = 'chadstart.yaml';
+const DEFAULT_CONFIG = 'chadstart.yaml';
 
 function printUsage() {
   console.log(`
-ChadStart - YAML-first Backend as a Service
+ChadStart - Config-driven Backend as a Service
 
 Usage:
-  npx chadstart dev               Start server with hot-reload on YAML changes
+  npx chadstart dev               Start server with hot-reload on config changes
   npx chadstart start             Start server (production mode)
-  npx chadstart build             Validate YAML config and print schema summary
+  npx chadstart build             Validate config and print schema summary
   npx chadstart seed              Seed the database with dummy data
   npx chadstart migrate           Run pending database migrations
-  npx chadstart migrate:generate  Generate migration from YAML diff (git-based)
+  npx chadstart migrate:generate  Generate migration from config diff (git-based)
   npx chadstart migrate:status    Show current migration status
 
 Options:
-  --config <file>         Path to YAML config (default: chadstart.yaml)
+  --config <file>         Path to config file (default: auto-discover)
+                          Supported formats: yaml, json, json5, jsonnet, js
   --port <number>         Override port from config
   --migrations-dir <dir>  Path to migrations directory (default: migrations)
   --description <text>    Description for generated migration
@@ -31,6 +32,7 @@ Options:
 Examples:
   npx chadstart dev
   npx chadstart dev --config my-backend.yaml
+  npx chadstart dev --config chadstart.json
   npx chadstart start --port 8080
   npx chadstart migrate:generate --description add-posts-table
   npx chadstart migrate
@@ -42,7 +44,16 @@ function getOption(flag) {
   return idx !== -1 ? args[idx + 1] : null;
 }
 
-const yamlPath = path.resolve(getOption('--config') || process.env.CHADSTART_FILE_PATH || DEFAULT_YAML);
+function resolveConfigPath() {
+  const explicit = getOption('--config') || process.env.CHADSTART_FILE_PATH;
+  if (explicit) return path.resolve(explicit);
+  // Auto-discover: try each supported filename in priority order
+  const { discoverConfigFile } = require('../core/config-loader');
+  const found = discoverConfigFile(process.cwd());
+  return found || path.resolve(DEFAULT_CONFIG); // fall back to default for error messages
+}
+
+const configPath = resolveConfigPath();
 const portOverride = getOption('--port');
 
 if (!command || command === 'help' || command === '--help' || command === '-h') {
@@ -119,19 +130,19 @@ async function runCreate() {
 }
 
 async function runSeed() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
   try {
-    const { loadYaml } = require('../core/yaml-loader');
+    const { loadConfig } = require('../core/config-loader');
     const { validateSchema } = require('../core/schema-validator');
     const { buildCore } = require('../core/entity-engine');
     const { initDb } = require('../core/db');
     const { seedAll } = require('../core/seeder');
 
-    const config = loadYaml(yamlPath);
+    const config = loadConfig(configPath);
     validateSchema(config);
     const core = buildCore(config);
     initDb(core);
@@ -158,19 +169,19 @@ async function runSeed() {
 }
 
 async function runStart() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
   applyPortOverride();
   const { startServer } = require('../server/express-server');
-  await startServer(yamlPath);
+  await startServer(configPath);
 }
 
 async function runDev() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
@@ -186,7 +197,7 @@ async function runDev() {
       // Re-require fresh server module on each reload
       clearRequireCache();
       const { startServer } = require('../server/express-server');
-      const result = await startServer(yamlPath);
+      const result = await startServer(configPath);
       currentServer = result.server;
     } catch (err) {
       console.error('[dev] Failed to start server:', err.message);
@@ -198,12 +209,12 @@ async function runDev() {
   try {
     const chokidar = require('chokidar');
     // Watch YAML config
-    const watcher = chokidar.watch(yamlPath, { ignoreInitial: true });
+    const watcher = chokidar.watch(configPath, { ignoreInitial: true });
     watcher.on('change', async () => {
-      console.log(`\n[dev] ${path.basename(yamlPath)} changed — restarting...\n`);
+      console.log(`\n[dev] ${path.basename(configPath)} changed — restarting...\n`);
       await boot();
     });
-    console.log(`[dev] Watching ${yamlPath} for changes...\n`);
+    console.log(`[dev] Watching ${configPath} for changes...\n`);
 
     // Watch the functions folder for hot reload of function files
     const functionsDir = path.resolve(process.env.CHADSTART_FUNCTIONS_FOLDER || 'functions');
@@ -228,17 +239,17 @@ async function runDev() {
 }
 
 function runBuild() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
   try {
-    const { loadYaml } = require('../core/yaml-loader');
+    const { loadConfig } = require('../core/config-loader');
     const { validateSchema } = require('../core/schema-validator');
     const { buildCore } = require('../core/entity-engine');
 
-    const config = loadYaml(yamlPath);
+    const config = loadConfig(configPath);
     validateSchema(config);
     const core = buildCore(config);
 
@@ -290,20 +301,20 @@ const migrationsDir = path.resolve(getOption('--migrations-dir') || 'migrations'
 const migrationDescription = getOption('--description') || null;
 
 async function runMigrate() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
   try {
-    const { loadYaml } = require('../core/yaml-loader');
+    const { loadConfig } = require('../core/config-loader');
     const { validateSchema } = require('../core/schema-validator');
     const { buildCore } = require('../core/entity-engine');
     const { initDb, closeDb } = require('../core/db');
     const { runMigrations, buildExecQueryFn } = require('../core/migrations');
     const dbModule = require('../core/db');
 
-    const config = loadYaml(yamlPath);
+    const config = loadConfig(configPath);
     validateSchema(config);
     const core = buildCore(config);
     await initDb(core);
@@ -331,8 +342,8 @@ async function runMigrate() {
 }
 
 async function runMigrateGenerate() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
@@ -341,7 +352,7 @@ async function runMigrateGenerate() {
 
     console.log('\n📝 Generating migration from YAML diff...\n');
 
-    const result = generateMigration(yamlPath, migrationsDir, migrationDescription);
+    const result = generateMigration(configPath, migrationsDir, migrationDescription);
 
     if (result.isEmpty) {
       console.log('  ℹ️  No schema changes detected — nothing to generate.\n');
@@ -358,20 +369,20 @@ async function runMigrateGenerate() {
 }
 
 async function runMigrateStatus() {
-  if (!fs.existsSync(yamlPath)) {
-    console.error(`Config not found: ${yamlPath}`);
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
     process.exit(1);
   }
 
   try {
-    const { loadYaml } = require('../core/yaml-loader');
+    const { loadConfig } = require('../core/config-loader');
     const { validateSchema } = require('../core/schema-validator');
     const { buildCore } = require('../core/entity-engine');
     const { initDb, closeDb } = require('../core/db');
     const { getMigrationStatus, buildExecQueryFn } = require('../core/migrations');
     const dbModule = require('../core/db');
 
-    const config = loadYaml(yamlPath);
+    const config = loadConfig(configPath);
     validateSchema(config);
     const core = buildCore(config);
     await initDb(core);

package/core/config-loader.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const YAML = require('yaml');
+const JSON5 = require('json5');
+const logger = require('../utils/logger');
+
+const JSONNET_TIMEOUT_MS = 10000;
+
+// ─── Supported config file names (checked in priority order) ─────────────────
+
+const CONFIG_FILENAMES = [
+  'chadstart.yaml',
+  'chadstart.yml',
+  'chadstart.json',
+  'chadstart.json5',
+  'chadstart.jsonnet',
+  'chadstart.config.js',
+  'chadstart.config.cjs',
+];
+
+// ─── Format detection ────────────────────────────────────────────────────────
+
+/**
+ * Map a file extension to a config format identifier.
+ *
+ * @param {string} filePath
+ * @returns {'yaml'|'json'|'json5'|'jsonnet'|'js'}
+ */
+function detectFormat(filePath) {
+  const base = path.basename(filePath);
+  if (base.endsWith('.config.js') || base.endsWith('.config.cjs')) return 'js';
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.yaml':
+    case '.yml':
+      return 'yaml';
+    case '.json':
+      return 'json';
+    case '.json5':
+      return 'json5';
+    case '.jsonnet':
+      return 'jsonnet';
+    case '.js':
+    case '.cjs':
+      return 'js';
+    default:
+      return 'yaml'; // default fallback
+  }
+}
+
+/**
+ * Returns true when the format supports writing back through saveConfig.
+ */
+function isWritableFormat(format) {
+  return format === 'yaml' || format === 'json' || format === 'json5';
+}
+
+// ─── Auto-discovery ──────────────────────────────────────────────────────────
+
+/**
+ * Discover the first matching config file inside `dir`.
+ * Returns the absolute path, or null when nothing is found.
+ *
+ * @param {string} [dir=process.cwd()]
+ * @returns {string|null}
+ */
+function discoverConfigFile(dir) {
+  const base = dir || process.cwd();
+  for (const name of CONFIG_FILENAMES) {
+    const candidate = path.resolve(base, name);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ─── Parsers ─────────────────────────────────────────────────────────────────
+
+function parseYaml(raw) {
+  return YAML.parse(raw);
+}
+
+function parseJson(raw) {
+  return JSON.parse(raw);
+}
+
+function parseJson5(raw) {
+  return JSON5.parse(raw);
+}
+
+function parseJsonnet(filePath) {
+  const { execFileSync } = require('child_process');
+  try {
+    const stdout = execFileSync('jsonnet', [filePath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: JSONNET_TIMEOUT_MS,
+    }).toString();
+    return JSON.parse(stdout);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(
+        'Jsonnet config detected but the "jsonnet" CLI is not installed. ' +
+          'Install it (https://jsonnet.org) or convert your config to YAML/JSON.',
+      );
+    }
+    throw new Error(`Failed to evaluate Jsonnet config: ${err.stderr || err.message}`);
+  }
+}
+
+function parseJsConfig(filePath) {
+  // Clear require cache so edits are picked up on hot-reload
+  try { delete require.cache[require.resolve(filePath)]; } catch { /* first load */ }
+  const mod = require(filePath);
+  const config = mod && mod.__esModule ? mod.default : mod;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`JS config must export a plain object: ${filePath}`);
+  }
+  return config;
+}
+
+// ─── Load ────────────────────────────────────────────────────────────────────
+
+/**
+ * Load and parse a config file in any supported format.
+ *
+ * @param {string} filePath  Absolute or relative path to the config file.
+ * @returns {object}         Parsed config object.
+ */
+function loadConfig(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Config file not found: ${resolved}`);
+  }
+
+  const format = detectFormat(resolved);
+  let config;
+
+  switch (format) {
+    case 'yaml': {
+      const raw = fs.readFileSync(resolved, 'utf8');
+      config = parseYaml(raw);
+      break;
+    }
+    case 'json': {
+      const raw = fs.readFileSync(resolved, 'utf8');
+      config = parseJson(raw);
+      break;
+    }
+    case 'json5': {
+      const raw = fs.readFileSync(resolved, 'utf8');
+      config = parseJson5(raw);
+      break;
+    }
+    case 'jsonnet':
+      config = parseJsonnet(resolved);
+      break;
+    case 'js':
+      config = parseJsConfig(resolved);
+      break;
+    default: {
+      const raw = fs.readFileSync(resolved, 'utf8');
+      config = parseYaml(raw);
+    }
+  }
+
+  logger.debug('Loaded config (%s) from %s', format, resolved);
+  return config;
+}
+
+// ─── Save ────────────────────────────────────────────────────────────────────
+
+/**
+ * Save a config object back to disk in the file's native format.
+ *
+ * For YAML files, comments in unchanged top-level sections are preserved using
+ * the yaml Document API.  JSON and JSON5 files are pretty-printed.
+ * Jsonnet and JS configs cannot be written back (they may contain logic).
+ *
+ * @param {string} filePath  Path to the config file.
+ * @param {object} config    Plain-JS config object (already validated).
+ */
+function saveConfig(filePath, config) {
+  const resolved = path.resolve(filePath);
+  const format = detectFormat(resolved);
+
+  if (!isWritableFormat(format)) {
+    throw new Error(
+      `Cannot save config: ${format} format is read-only. ` +
+        'Convert to YAML, JSON, or JSON5 to enable saving from the admin UI.',
+    );
+  }
+
+  switch (format) {
+    case 'yaml':
+      saveYamlFile(resolved, config);
+      break;
+    case 'json':
+      fs.writeFileSync(resolved, JSON.stringify(config, null, 2) + '\n', 'utf8');
+      break;
+    case 'json5':
+      fs.writeFileSync(resolved, JSON5.stringify(config, null, 2) + '\n', 'utf8');
+      break;
+    default:
+      break;
+  }
+
+  logger.debug('Saved config (%s) to %s', format, resolved);
+}
+
+/**
+ * YAML-specific save that preserves comments via the Document API.
+ * Extracted from the original yaml-loader.js.
+ */
+function saveYamlFile(resolved, config) {
+  let doc;
+  if (fs.existsSync(resolved)) {
+    const raw = fs.readFileSync(resolved, 'utf8');
+    doc = YAML.parseDocument(raw);
+
+    const existing = doc.toJS() || {};
+    const existingKeys = Object.keys(existing);
+    const newKeys = Object.keys(config);
+
+    for (const key of newKeys) {
+      doc.set(key, config[key]);
+    }
+    for (const key of existingKeys) {
+      if (!newKeys.includes(key)) {
+        doc.delete(key);
+      }
+    }
+  } else {
+    doc = new YAML.Document(config);
+  }
+
+  fs.writeFileSync(resolved, doc.toString(), 'utf8');
+}
+
+// ─── Parse raw content by format (used by migrations git-show) ───────────────
+
+/**
+ * Parse raw file content using the parser matching the given format.
+ *
+ * @param {string} raw     Raw file content (UTF-8 string).
+ * @param {'yaml'|'json'|'json5'} format
+ * @returns {object}
+ */
+function parseRaw(raw, format) {
+  switch (format) {
+    case 'json':  return parseJson(raw);
+    case 'json5': return parseJson5(raw);
+    case 'yaml':
+    default:      return parseYaml(raw);
+  }
+}
+
+module.exports = {
+  CONFIG_FILENAMES,
+  detectFormat,
+  isWritableFormat,
+  discoverConfigFile,
+  loadConfig,
+  saveConfig,
+  parseRaw,
+};

package/core/migrations.js

@@ -8,16 +8,22 @@ const logger = require('../utils/logger');
 
 const { buildCore, toSnakeCase } = require('./entity-engine');
 const { DB_ENGINE, q, sqlType, idColType, authStrType } = require('./db');
+const { detectFormat, parseRaw, loadConfig } = require('./config-loader');
 
 // ─── Git helpers ──────────────────────────────────────────────────────────────
 
 /**
- * Retrieve the last committed version of a file using git.
+ * Retrieve the last committed version of a config file using git.
  * Returns null if the file has no committed history (brand-new / untracked).
  */
-function getLastCommittedYaml(yamlPath) {
+function getLastCommittedConfig(configPath) {
   try {
-    const resolved = path.resolve(yamlPath);
+    const resolved = path.resolve(configPath);
+    const format = detectFormat(resolved);
+
+    // JS / Jsonnet configs can't be reconstructed from raw git content alone
+    if (format === 'js' || format === 'jsonnet') return null;
+
     const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
       cwd: path.dirname(resolved),
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -30,21 +36,17 @@ function getLastCommittedYaml(yamlPath) {
       stdio: ['pipe', 'pipe', 'pipe'],
     }).toString();
 
-    return YAML.parse(raw);
+    return parseRaw(raw, format);
   } catch {
     return null;
   }
 }
 
 /**
- * Load the current YAML file from disk and return the parsed object.
+ * Load the current config file from disk and return the parsed object.
  */
-function loadCurrentYaml(yamlPath) {
-  const resolved = path.resolve(yamlPath);
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`YAML config not found: ${resolved}`);
-  }
-  return YAML.parse(fs.readFileSync(resolved, 'utf8'));
+function loadCurrentConfig(configPath) {
+  return loadConfig(configPath);
 }
 
 
@@ -374,17 +376,17 @@ async function getMigrationStatus(migrationsDir, execQueryFn) {
 // ─── High-level commands ──────────────────────────────────────────────────────
 
 /**
- * Generate a migration by diffing the current YAML against the last committed
+ * Generate a migration by diffing the current config against the last committed
  * version in git. Writes numbered SQL files to the migrations directory.
  *
- * @param {string} yamlPath        Path to the chadstart YAML config file.
+ * @param {string} configPath      Path to the config file (any supported format).
  * @param {string} migrationsDir   Path to the migrations directory.
  * @param {string} [description]   Optional description for the migration.
  * @returns {{ doPath, undoPath, version, isEmpty } | null}
  */
-function generateMigration(yamlPath, migrationsDir, description) {
-  const currentConfig = loadCurrentYaml(yamlPath);
-  const oldConfig = getLastCommittedYaml(yamlPath);
+function generateMigration(configPath, migrationsDir, description) {
+  const currentConfig = loadCurrentConfig(configPath);
+  const oldConfig = getLastCommittedConfig(configPath);
 
   const newCore = buildCore(currentConfig);
   const oldCore = oldConfig ? buildCore(oldConfig) : null;
@@ -408,8 +410,11 @@ function generateMigration(yamlPath, migrationsDir, description) {
 
 module.exports = {
   // Git helpers
-  getLastCommittedYaml,
-  loadCurrentYaml,
+  getLastCommittedConfig,
+  loadCurrentConfig,
+  // Backward-compatible aliases
+  getLastCommittedYaml: getLastCommittedConfig,
+  loadCurrentYaml: loadCurrentConfig,
   // Diff engine
   diffCores,
   // SQL generation

package/core/yaml-loader.js

@@ -1,64 +1,19 @@
 '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.
+ * Backward-compatible re-exports.
+ *
+ * All new code should import from `./config-loader` directly.
+ * These wrappers keep existing callers (tests, plugins) working unchanged.
  */
+const { loadConfig, saveConfig } = require('./config-loader');
+
 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;
+  return loadConfig(filePath);
 }
 
-/**
- * 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);
+  return saveConfig(filePath, config);
 }
 
 module.exports = { loadYaml, saveYaml };

package/docs/llm-rules.md

@@ -75,7 +75,7 @@ If you already have an existing project and want to add AI rules manually, creat
 | **GitHub Copilot** | `.github/copilot-instructions.md`              |
 | **Windsurf**       | `.windsurf/rules/chadstart.md`                 |
 
-You can base your rules file on the [chadstart.example.yml](https://github.com/saulmmendoza/chadstart.com/blob/main/chadstart.example.yml) reference file, which documents every available configuration option.
+You can base your rules file on the [chadstart.example.yaml](https://github.com/saulmmendoza/chadstart.com/blob/main/chadstart.example.yaml) reference file, which documents every available configuration option.
 
 !!! tip
     Keep your rules file up to date whenever you upgrade ChadStart. Newer versions may introduce new field types, options, or top-level blocks that your AI assistant won't know about unless the rules file is updated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chadstart",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "YAML-first Backend as a Service — define your entire backend in one YAML file",
   "main": "server/express-server.js",
   "bin": {
@@ -49,6 +49,7 @@
     "express-rate-limit": "^8.3.1",
     "grant": "^5.4.24",
     "htmx.org": "2.0.4",
+    "json5": "^2.2.3",
     "jsonwebtoken": "^9.0.3",
     "mysql2": "^3.20.0",
     "node-cron": "^4.2.1",

package/server/express-server.js

@@ -8,7 +8,7 @@ const express = require('express');
 const swaggerUi = require('swagger-ui-express');
 const rateLimit = require('express-rate-limit');
 
-const { loadYaml, saveYaml } = require('../core/yaml-loader');
+const { loadConfig, saveConfig, detectFormat, isWritableFormat } = require('../core/config-loader');
 const { validateSchema } = require('../core/schema-validator');
 const { buildCore } = require('../core/entity-engine');
 const { initDb, findAll, findAllSimple, create: dbCreate } = require('../core/db');
@@ -81,18 +81,19 @@ function buildApiLimiters(core) {
 }
 
 /**
- * Build an Express application for the given YAML config.
+ * Build an Express application for the given config file.
  *
- * @param {string}        yamlPath  Path to the chadstart.yaml file.
- * @param {Function|null} reloadFn  When provided, the PUT /admin/config route will
- *                                  trigger this callback after saving so the running
- *                                  server picks up the new config without a restart.
+ * @param {string}        configPath  Path to the config file (any supported format).
+ * @param {Function|null} reloadFn    When provided, the PUT /admin/config route will
+ *                                    trigger this callback after saving so the running
+ *                                    server picks up the new config without a restart.
  * @returns {{ app: import('express').Application, core: object }}
  */
-async function buildApp(yamlPath, reloadFn) {
-  const config = loadYaml(yamlPath);
+async function buildApp(configPath, reloadFn) {
+  const config = loadConfig(configPath);
   validateSchema(config);
   const core = buildCore(config);
+  const configFormat = detectFormat(configPath);
   logger.info(`Loading "${core.name}"...`);
 
   // Initialize OpenTelemetry (singleton — no-op on hot reload)
@@ -100,7 +101,7 @@ async function buildApp(yamlPath, reloadFn) {
   await initTelemetry(telConfig);
 
   const dbPath = core.database
-    ? path.resolve(path.dirname(yamlPath), core.database)
+    ? path.resolve(path.dirname(configPath), core.database)
     : undefined;
   await initDb(core, dbPath);
   await initApiKeys();
@@ -211,7 +212,7 @@ async function buildApp(yamlPath, reloadFn) {
   });
 
   // ── Admin config endpoints ────────────────────────────────────────────
-  // GET /admin/config — return the current YAML config as JSON (auth required)
+  // GET /admin/config — return the current config as JSON (auth required)
   app.get('/admin/config', adminRateLimiter, (req, res) => {
     const header = req.headers.authorization;
     if (!header || !header.startsWith('Bearer ')) {
@@ -221,13 +222,30 @@ async function buildApp(yamlPath, reloadFn) {
       return res.status(401).json({ error: 'Invalid token' });
     }
     try {
-      res.json(loadYaml(yamlPath));
+      res.set('X-Config-Format', configFormat);
+      res.json(loadConfig(configPath));
     } catch (e) {
       res.status(500).json({ error: e.message });
     }
   });
 
-  // PUT /admin/config — receive JSON config, validate, save as YAML, then hot-reload
+  // GET /admin/config-info — return metadata about the config file
+  app.get('/admin/config-info', adminRateLimiter, (req, res) => {
+    const header = req.headers.authorization;
+    if (!header || !header.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    try { verifyToken(header.slice(7)); } catch {
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+    res.json({
+      format: configFormat,
+      file: path.basename(configPath),
+      writable: isWritableFormat(configFormat),
+    });
+  });
+
+  // PUT /admin/config — receive JSON config, validate, save in original format, then hot-reload
   app.put('/admin/config', adminRateLimiter, (req, res) => {
     const header = req.headers.authorization;
     if (!header || !header.startsWith('Bearer ')) {
@@ -246,7 +264,7 @@ async function buildApp(yamlPath, reloadFn) {
       return res.status(400).json({ error: e.message });
     }
     try {
-      saveYaml(yamlPath, newConfig);
+      saveConfig(configPath, newConfig);
       if (reloadFn) {
         // Schedule hot reload after the response has been fully flushed
         res.on('finish', () => {
@@ -258,7 +276,7 @@ async function buildApp(yamlPath, reloadFn) {
       }
     } catch (e) {
       logger.error('Failed to save config:', e.message);
-      res.status(500).json({ error: 'Failed to save config' });
+      res.status(500).json({ error: e.message });
     }
   });
 
@@ -503,14 +521,14 @@ async function buildApp(yamlPath, reloadFn) {
   return { app, core };
 }
 
-async function createServer(yamlPath) {
-  const { app, core } = await buildApp(yamlPath, null);
+async function createServer(configPath) {
+  const { app, core } = await buildApp(configPath, null);
   const server = http.createServer(app);
   initRealtime(server);
   return { app, server, core };
 }
 
-async function startServer(yamlPath) {
+async function startServer(configPath) {
   // ── Dispatcher pattern ───────────────────────────────────────────────
   // The HTTP server and WebSocket server are created once and never replaced.
   // Hot reload works by rebuilding the Express app and swapping the handler
@@ -523,7 +541,7 @@ async function startServer(yamlPath) {
 
   async function reload() {
     logger.info('Reloading config…');
-    const result = await buildApp(yamlPath, reload);
+    const result = await buildApp(configPath, reload);
     currentApp = result.app;
     logger.info(`Config loaded: "${result.core.name}"`);
     return result;

package/test/config-loader.test.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const {
+  CONFIG_FILENAMES,
+  detectFormat,
+  isWritableFormat,
+  discoverConfigFile,
+  loadConfig,
+  saveConfig,
+  parseRaw,
+} = require('../core/config-loader');
+
+function tmpPath(ext) {
+  return path.join(os.tmpdir(), `chadstart-cl-${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`);
+}
+
+describe('config-loader', () => {
+  // ── detectFormat ─────────────────────────────────────────────────────────
+  describe('detectFormat', () => {
+    it('detects .yaml as yaml', () => assert.strictEqual(detectFormat('app.yaml'), 'yaml'));
+    it('detects .yml as yaml', () => assert.strictEqual(detectFormat('app.yml'), 'yaml'));
+    it('detects .json as json', () => assert.strictEqual(detectFormat('app.json'), 'json'));
+    it('detects .json5 as json5', () => assert.strictEqual(detectFormat('app.json5'), 'json5'));
+    it('detects .jsonnet as jsonnet', () => assert.strictEqual(detectFormat('app.jsonnet'), 'jsonnet'));
+    it('detects .config.js as js', () => assert.strictEqual(detectFormat('chadstart.config.js'), 'js'));
+    it('detects .config.cjs as js', () => assert.strictEqual(detectFormat('chadstart.config.cjs'), 'js'));
+    it('defaults to yaml for unknown extensions', () => assert.strictEqual(detectFormat('app.txt'), 'yaml'));
+  });
+
+  // ── isWritableFormat ─────────────────────────────────────────────────────
+  describe('isWritableFormat', () => {
+    it('yaml is writable', () => assert.ok(isWritableFormat('yaml')));
+    it('json is writable', () => assert.ok(isWritableFormat('json')));
+    it('json5 is writable', () => assert.ok(isWritableFormat('json5')));
+    it('jsonnet is not writable', () => assert.ok(!isWritableFormat('jsonnet')));
+    it('js is not writable', () => assert.ok(!isWritableFormat('js')));
+  });
+
+  // ── discoverConfigFile ───────────────────────────────────────────────────
+  describe('discoverConfigFile', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cs-disc-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('returns null when no config file exists', () => {
+      assert.strictEqual(discoverConfigFile(tmpDir), null);
+    });
+
+    it('discovers chadstart.yaml', () => {
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.yaml'), 'name: Test\n');
+      assert.strictEqual(discoverConfigFile(tmpDir), path.join(tmpDir, 'chadstart.yaml'));
+    });
+
+    it('discovers chadstart.json', () => {
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.json'), '{"name":"Test"}');
+      assert.strictEqual(discoverConfigFile(tmpDir), path.join(tmpDir, 'chadstart.json'));
+    });
+
+    it('discovers chadstart.json5', () => {
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.json5'), '{name:"Test"}');
+      assert.strictEqual(discoverConfigFile(tmpDir), path.join(tmpDir, 'chadstart.json5'));
+    });
+
+    it('prefers yaml over json when both exist', () => {
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.yaml'), 'name: YAML\n');
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.json'), '{"name":"JSON"}');
+      const found = discoverConfigFile(tmpDir);
+      assert.strictEqual(path.basename(found), 'chadstart.yaml');
+    });
+
+    it('falls back to json when yaml is absent', () => {
+      fs.writeFileSync(path.join(tmpDir, 'chadstart.json'), '{"name":"JSON"}');
+      const found = discoverConfigFile(tmpDir);
+      assert.strictEqual(path.basename(found), 'chadstart.json');
+    });
+  });
+
+  // ── loadConfig ───────────────────────────────────────────────────────────
+  describe('loadConfig', () => {
+    it('loads the existing chadstart.yaml', () => {
+      const config = loadConfig(path.resolve(__dirname, '..', 'chadstart.yaml'));
+      assert.strictEqual(typeof config.name, 'string');
+      assert.ok(config.entities);
+    });
+
+    it('throws on missing file', () => {
+      assert.throws(() => loadConfig('/nonexistent.yaml'), /not found/i);
+    });
+
+    it('loads a JSON config file', () => {
+      const tmp = tmpPath('.json');
+      fs.writeFileSync(tmp, JSON.stringify({ name: 'JSONApp', port: 4000 }), 'utf8');
+      try {
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'JSONApp');
+        assert.strictEqual(config.port, 4000);
+      } finally {
+        fs.unlinkSync(tmp);
+      }
+    });
+
+    it('loads a JSON5 config file', () => {
+      const tmp = tmpPath('.json5');
+      fs.writeFileSync(tmp, '{\n  // App name\n  name: "JSON5App",\n  port: 5000,\n}\n', 'utf8');
+      try {
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'JSON5App');
+        assert.strictEqual(config.port, 5000);
+      } finally {
+        fs.unlinkSync(tmp);
+      }
+    });
+
+    it('loads a .config.js config file', () => {
+      const tmp = path.join(os.tmpdir(), `chadstart-cl-${Date.now()}.config.js`);
+      fs.writeFileSync(tmp, 'module.exports = { name: "JSConfig", port: 6000 };\n', 'utf8');
+      try {
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'JSConfig');
+        assert.strictEqual(config.port, 6000);
+      } finally {
+        fs.unlinkSync(tmp);
+        try { delete require.cache[require.resolve(tmp)]; } catch { /* */ }
+      }
+    });
+
+    it('loads a YAML (.yml) config file', () => {
+      const tmp = tmpPath('.yml');
+      fs.writeFileSync(tmp, 'name: YMLApp\nport: 7000\n', 'utf8');
+      try {
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'YMLApp');
+        assert.strictEqual(config.port, 7000);
+      } finally {
+        fs.unlinkSync(tmp);
+      }
+    });
+  });
+
+  // ── saveConfig ───────────────────────────────────────────────────────────
+  describe('saveConfig', () => {
+    it('saves and round-trips a YAML file', () => {
+      const tmp = tmpPath('.yaml');
+      try {
+        saveConfig(tmp, { name: 'SaveYAML', port: 3000 });
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'SaveYAML');
+        assert.strictEqual(config.port, 3000);
+      } finally {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      }
+    });
+
+    it('saves and round-trips a JSON file', () => {
+      const tmp = tmpPath('.json');
+      try {
+        saveConfig(tmp, { name: 'SaveJSON', port: 4000 });
+        const raw = fs.readFileSync(tmp, 'utf8');
+        assert.ok(raw.includes('"name"'), 'JSON file should contain double-quoted keys');
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'SaveJSON');
+        assert.strictEqual(config.port, 4000);
+      } finally {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      }
+    });
+
+    it('saves and round-trips a JSON5 file', () => {
+      const tmp = tmpPath('.json5');
+      try {
+        saveConfig(tmp, { name: 'SaveJSON5', port: 5000 });
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.name, 'SaveJSON5');
+        assert.strictEqual(config.port, 5000);
+      } finally {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      }
+    });
+
+    it('throws for read-only formats (js)', () => {
+      const tmp = path.join(os.tmpdir(), `chadstart-cl-${Date.now()}.config.js`);
+      assert.throws(
+        () => saveConfig(tmp, { name: 'Nope' }),
+        /read-only/i,
+      );
+    });
+
+    it('throws for read-only formats (jsonnet)', () => {
+      const tmp = tmpPath('.jsonnet');
+      assert.throws(
+        () => saveConfig(tmp, { name: 'Nope' }),
+        /read-only/i,
+      );
+    });
+
+    it('preserves YAML comments in unchanged sections', () => {
+      const tmp = tmpPath('.yaml');
+      try {
+        fs.writeFileSync(tmp, '# App name\nname: Blog\n\n# Port\nport: 3000\n', 'utf8');
+        saveConfig(tmp, { name: 'Blog', port: 4000 });
+        const raw = fs.readFileSync(tmp, 'utf8');
+        assert.ok(raw.includes('# App name'), 'Comment on name should be preserved');
+        assert.ok(raw.includes('# Port'), 'Comment on port should be preserved');
+        const config = loadConfig(tmp);
+        assert.strictEqual(config.port, 4000);
+      } finally {
+        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      }
+    });
+  });
+
+  // ── parseRaw ─────────────────────────────────────────────────────────────
+  describe('parseRaw', () => {
+    it('parses raw YAML', () => {
+      const obj = parseRaw('name: Test\nport: 3000\n', 'yaml');
+      assert.strictEqual(obj.name, 'Test');
+    });
+
+    it('parses raw JSON', () => {
+      const obj = parseRaw('{"name":"Test","port":3000}', 'json');
+      assert.strictEqual(obj.name, 'Test');
+    });
+
+    it('parses raw JSON5', () => {
+      const obj = parseRaw('{name:"Test",port:3000}', 'json5');
+      assert.strictEqual(obj.name, 'Test');
+    });
+
+    it('defaults to YAML for unknown format', () => {
+      const obj = parseRaw('name: Fallback\n', 'unknown');
+      assert.strictEqual(obj.name, 'Fallback');
+    });
+  });
+
+  // ── CONFIG_FILENAMES ─────────────────────────────────────────────────────
+  describe('CONFIG_FILENAMES', () => {
+    it('includes yaml, yml, json, json5, jsonnet, and js formats', () => {
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.yaml'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.yml'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.json'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.json5'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.jsonnet'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.config.js'));
+      assert.ok(CONFIG_FILENAMES.includes('chadstart.config.cjs'));
+    });
+  });
+});