chadstart 1.0.4 → 1.0.6

package/core/auth.js

@@ -7,6 +7,10 @@
  *   POST /api/auth/:slug/signup
  *   POST /api/auth/:slug/login
  *   GET  /api/auth/:slug/me
+ *   POST /api/auth/:slug/request-verification
+ *   POST /api/auth/:slug/confirm-verification
+ *   POST /api/auth/:slug/request-password-reset
+ *   POST /api/auth/:slug/confirm-password-reset
  *   GET  /api/auth/:slug/api-keys
  *   POST /api/auth/:slug/api-keys
  *   DELETE /api/auth/:slug/api-keys/:id
@@ -42,6 +46,25 @@ function signToken(payload, expiresIn) {
 }
 function verifyToken(token) { return jwt.verify(token, JWT_SECRET); }
 
+/** Generate a cryptographically secure random hex token. */
+function generateSecureToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+// ─── Default email templates ─────────────────────────────────────────────────
+
+const DEFAULT_VERIFICATION_TEMPLATE = {
+  subject: 'Verify your email for {{appName}}',
+  text: 'Hi {{name}},\n\nPlease verify your email address by using the following token:\n\n{{token}}\n\nOr click this link: {{link}}\n\nThanks,\n{{appName}}',
+  html: '<h2>Verify your email</h2><p>Hi {{name}},</p><p>Please verify your email address by clicking the link below:</p><p><a href="{{link}}">Verify Email</a></p><p>Or use this token: <code>{{token}}</code></p><p>Thanks,<br>{{appName}}</p>',
+};
+
+const DEFAULT_PASSWORD_RESET_TEMPLATE = {
+  subject: 'Reset your password for {{appName}}',
+  text: 'Hi {{name}},\n\nYou requested a password reset. Use the following token:\n\n{{token}}\n\nOr click this link: {{link}}\n\nThis link expires in 1 hour.\n\nIf you did not request this, please ignore this email.\n\nThanks,\n{{appName}}',
+  html: '<h2>Reset your password</h2><p>Hi {{name}},</p><p>You requested a password reset. Click the link below:</p><p><a href="{{link}}">Reset Password</a></p><p>Or use this token: <code>{{token}}</code></p><p>This link expires in 1 hour.</p><p>If you did not request this, please ignore this email.</p><p>Thanks,<br>{{appName}}</p>',
+};
+
 // ─── API Keys ─────────────────────────────────────────────────────────────────
 
 /**
@@ -231,6 +254,34 @@ function registerApiKeyRoutes(app, core) {
 
 function registerAuthRoutes(app, core, emit) {
   const _emit = typeof emit === 'function' ? emit : () => {};
+
+  // Lazily load email module to avoid circular dependency at module load time
+  let _emailMod;
+  function _getEmail() {
+    if (!_emailMod) _emailMod = require('./email');
+    return _emailMod;
+  }
+
+  /** Try to send an email — logs and swallows errors so auth flow still succeeds when SMTP is down. */
+  async function _trySend(opts) {
+    try {
+      await _getEmail().sendEmail(opts);
+    } catch (e) {
+      logger.warn(`Email send failed (${opts.to}): ${e.message}`);
+    }
+  }
+
+  /** Merge user-defined template with built-in default. */
+  function _tpl(kind) {
+    const defaults = kind === 'verification' ? DEFAULT_VERIFICATION_TEMPLATE : DEFAULT_PASSWORD_RESET_TEMPLATE;
+    const custom = ((core.email || {}).templates || {})[kind] || {};
+    return {
+      subject: custom.subject || defaults.subject,
+      text: custom.text || defaults.text,
+      html: custom.html || defaults.html,
+    };
+  }
+
   for (const entity of Object.values(core.authenticableEntities || {})) {
     const slug = entity.slug;
     const table = entity.tableName;
@@ -240,34 +291,135 @@ function registerAuthRoutes(app, core, emit) {
     const signupPolicies = (entity.policies || {}).signup;
     const signupForbidden = signupPolicies && signupPolicies.length > 0 && signupPolicies[0].access === 'forbidden';
 
+    // ── Signup ────────────────────────────────────────────────────────────
     app.post(`/api/auth/${slug}/signup`, async (req, res) => {
       try {
         if (signupForbidden) return res.status(403).json({ error: 'Signup is forbidden for this entity' });
         const { email, password, ...rest } = req.body || {};
         if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
         if ((await db.findAllSimple(table, { email })).length) return res.status(409).json({ error: 'Email already registered' });
-        const user = await db.create(table, { email, password: await bcrypt.hash(password, BCRYPT_ROUNDS), ...sanitize(rest) });
+
+        // Generate email verification token
+        const verificationToken = generateSecureToken();
+        const user = await db.create(table, {
+          email,
+          password: await bcrypt.hash(password, BCRYPT_ROUNDS),
+          emailVerified: 0,
+          emailVerificationToken: verificationToken,
+          ...sanitize(rest),
+        });
         _emit(`${entity.name}.created`, omitPassword(user));
+
+        // Send verification email (best-effort — does not block signup)
+        const tpl = _tpl('verification');
+        const vars = { appName: core.name, name: email, token: verificationToken, link: `${_appUrl()}/verify?token=${verificationToken}` };
+        _trySend({ to: email, subject: tpl.subject, text: tpl.text, html: tpl.html, vars });
+
         res.status(201).json({ token: signToken({ id: user.id, entity: entity.name }), user: omitPassword(user) });
       } catch (e) { logger.error('signup error', e.message); res.status(500).json({ error: e.message }); }
     });
 
+    // ── Login ─────────────────────────────────────────────────────────────
     app.post(`/api/auth/${slug}/login`, async (req, res) => {
       try {
         const { email, password } = req.body || {};
         if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
         const user = (await db.findAllSimple(table, { email }))[0];
         if (!user || !(await bcrypt.compare(password, user.password))) return res.status(401).json({ error: 'Invalid credentials' });
+
+        // Block login if email verification is required but not done
+        if (entity.requireEmailVerification && !user.emailVerified) {
+          return res.status(403).json({ error: 'Email not verified. Please verify your email before logging in.' });
+        }
+
         res.json({ token: signToken({ id: user.id, entity: entity.name }), user: omitPassword(user) });
       } catch (e) { logger.error('login error', e.message); res.status(500).json({ error: e.message }); }
     });
 
+    // ── Me ─────────────────────────────────────────────────────────────────
     app.get(`/api/auth/${slug}/me`, requireAuth(entity.name), async (req, res) => {
       const user = await db.findById(table, req.user.id);
       if (!user) return res.status(404).json({ error: 'User not found' });
       res.json(omitPassword(user));
     });
 
+    // ── Request Verification ──────────────────────────────────────────────
+    app.post(`/api/auth/${slug}/request-verification`, requireAuth(entity.name), async (req, res) => {
+      try {
+        const user = await db.findById(table, req.user.id);
+        if (!user) return res.status(404).json({ error: 'User not found' });
+        if (user.emailVerified) return res.json({ message: 'Email already verified' });
+
+        const token = generateSecureToken();
+        await db.update(table, user.id, { emailVerificationToken: token });
+
+        const tpl = _tpl('verification');
+        const vars = { appName: core.name, name: user.email, token, link: `${_appUrl()}/verify?token=${token}` };
+        await _trySend({ to: user.email, subject: tpl.subject, text: tpl.text, html: tpl.html, vars });
+
+        res.json({ message: 'Verification email sent' });
+      } catch (e) { logger.error('request-verification error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
+    // ── Confirm Verification ──────────────────────────────────────────────
+    app.post(`/api/auth/${slug}/confirm-verification`, async (req, res) => {
+      try {
+        const { token } = req.body || {};
+        if (!token) return res.status(400).json({ error: 'token is required' });
+
+        const user = (await db.findAllSimple(table, { emailVerificationToken: token }))[0];
+        if (!user) return res.status(400).json({ error: 'Invalid or expired verification token' });
+
+        await db.update(table, user.id, { emailVerified: 1, emailVerificationToken: null });
+        res.json({ message: 'Email verified successfully' });
+      } catch (e) { logger.error('confirm-verification error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
+    // ── Request Password Reset ────────────────────────────────────────────
+    app.post(`/api/auth/${slug}/request-password-reset`, async (req, res) => {
+      try {
+        const { email } = req.body || {};
+        if (!email) return res.status(400).json({ error: 'email is required' });
+
+        // Always return 200 to avoid leaking whether email exists
+        const user = (await db.findAllSimple(table, { email }))[0];
+        if (user) {
+          const token = generateSecureToken();
+          const expiry = new Date(Date.now() + 60 * 60 * 1000).toISOString(); // 1 hour
+          await db.update(table, user.id, { passwordResetToken: token, passwordResetExpiry: expiry });
+
+          const tpl = _tpl('passwordReset');
+          const vars = { appName: core.name, name: user.email, token, link: `${_appUrl()}/reset-password?token=${token}` };
+          _trySend({ to: user.email, subject: tpl.subject, text: tpl.text, html: tpl.html, vars });
+        }
+
+        res.json({ message: 'If an account with that email exists, a password reset email has been sent.' });
+      } catch (e) { logger.error('request-password-reset error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
+    // ── Confirm Password Reset ────────────────────────────────────────────
+    app.post(`/api/auth/${slug}/confirm-password-reset`, async (req, res) => {
+      try {
+        const { token, password } = req.body || {};
+        if (!token || !password) return res.status(400).json({ error: 'token and password are required' });
+
+        const user = (await db.findAllSimple(table, { passwordResetToken: token }))[0];
+        if (!user) return res.status(400).json({ error: 'Invalid or expired reset token' });
+
+        // Check expiry
+        if (!user.passwordResetExpiry || new Date(user.passwordResetExpiry) < new Date()) {
+          return res.status(400).json({ error: 'Reset token has expired' });
+        }
+
+        await db.update(table, user.id, {
+          password: await bcrypt.hash(password, BCRYPT_ROUNDS),
+          passwordResetToken: null,
+          passwordResetExpiry: null,
+        });
+        res.json({ message: 'Password reset successfully' });
+      } catch (e) { logger.error('confirm-password-reset error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
     logger.info(`  Registered auth routes at /api/auth/${slug}/`);
   }
 }
@@ -294,13 +446,18 @@ async function optionalAuth(req, _res, next) {
 }
 
 function omitPassword(user) {
-  const { password: _, ...rest } = user;
+  const { password: _, emailVerificationToken: _2, passwordResetToken: _3, passwordResetExpiry: _4, ...rest } = user;
   return rest;
 }
 
+/** Derive the app's base URL for email links. */
+function _appUrl() {
+  return process.env.APP_URL || process.env.BASE_URL || `http://localhost:${process.env.PORT || 3000}`;
+}
+
 module.exports = {
   registerAuthRoutes, registerApiKeyRoutes, initApiKeys,
   requireAuth, optionalAuth, resolveAuthHeader,
-  signToken, verifyToken, omitPassword, JWT_SECRET,
+  signToken, verifyToken, omitPassword, JWT_SECRET, generateSecureToken,
   createApiKey, listApiKeys, listAllApiKeys, deleteApiKey, verifyApiKeyStr,
 };

package/core/backup.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * Backup & Restore module for ChadStart.
+ *
+ * Supports SQLite (file copy), PostgreSQL (pg_dump), and MySQL (mysqldump).
+ *
+ * Configuration via YAML `backup` section:
+ *   backup:
+ *     dir: backups           # Directory for backup files (default: backups)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const db = require('./db');
+const logger = require('../utils/logger');
+
+const DB_ENGINE = db.DB_ENGINE;
+
+/**
+ * Get the backup directory. Creates it if it doesn't exist.
+ *
+ * @param {object|null} backupCfg  Value of `core.backup` (may be null).
+ * @returns {string}               Absolute path to backup directory.
+ */
+function getBackupDir(backupCfg) {
+  const dir = (backupCfg && backupCfg.dir) || process.env.BACKUP_DIR || 'backups';
+  const resolved = path.resolve(dir);
+  fs.mkdirSync(resolved, { recursive: true });
+  return resolved;
+}
+
+/**
+ * Generate a backup filename with timestamp.
+ *
+ * @param {string} ext  File extension (e.g. 'db', 'sql').
+ * @returns {string}
+ */
+function generateBackupName(ext) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const id = crypto.randomBytes(4).toString('hex');
+  return `backup-${ts}-${id}.${ext}`;
+}
+
+/**
+ * Create a backup of the database.
+ *
+ * @param {object|null} backupCfg  Value of `core.backup` (may be null).
+ * @returns {{ file: string, path: string, size: number, engine: string }}
+ */
+async function createBackup(backupCfg) {
+  const dir = getBackupDir(backupCfg);
+
+  if (DB_ENGINE === 'sqlite') {
+    const sqliteDb = db.getDb();
+    const name = generateBackupName('db');
+    const dest = path.join(dir, name);
+    await sqliteDb.backup(dest);
+    const stats = fs.statSync(dest);
+    logger.info(`Backup created: ${dest} (${stats.size} bytes)`);
+    return { file: name, path: dest, size: stats.size, engine: 'sqlite' };
+  }
+
+  if (DB_ENGINE === 'postgres') {
+    const name = generateBackupName('sql');
+    const dest = path.join(dir, name);
+    const args = [
+      '-h', process.env.DB_HOST || 'localhost',
+      '-p', process.env.DB_PORT || '5432',
+      '-U', process.env.DB_USERNAME || 'postgres',
+      '-d', process.env.DB_DATABASE || 'manifest',
+      '-f', dest,
+    ];
+    execFileSync('pg_dump', args, {
+      env: { ...process.env, PGPASSWORD: process.env.DB_PASSWORD || 'postgres' },
+      timeout: 120000,
+    });
+    const stats = fs.statSync(dest);
+    logger.info(`Backup created: ${dest} (${stats.size} bytes)`);
+    return { file: name, path: dest, size: stats.size, engine: 'postgres' };
+  }
+
+  if (DB_ENGINE === 'mysql') {
+    const name = generateBackupName('sql');
+    const dest = path.join(dir, name);
+    const args = [
+      '-h', process.env.DB_HOST || 'localhost',
+      '-P', process.env.DB_PORT || '3306',
+      '-u', process.env.DB_USERNAME || 'root',
+      `--result-file=${dest}`,
+      process.env.DB_DATABASE || 'manifest',
+    ];
+    const env = { ...process.env };
+    if (process.env.DB_PASSWORD) env.MYSQL_PWD = process.env.DB_PASSWORD;
+    execFileSync('mysqldump', args, { env, timeout: 120000 });
+    const stats = fs.statSync(dest);
+    logger.info(`Backup created: ${dest} (${stats.size} bytes)`);
+    return { file: name, path: dest, size: stats.size, engine: 'mysql' };
+  }
+
+  throw new Error(`Unsupported database engine for backup: ${DB_ENGINE}`);
+}
+
+/**
+ * Restore a database from a backup file.
+ *
+ * @param {string} backupFile  Filename of the backup (relative to backup dir).
+ * @param {object|null} backupCfg  Value of `core.backup` (may be null).
+ * @returns {{ success: boolean, message: string }}
+ */
+async function restoreBackup(backupFile, backupCfg) {
+  const dir = getBackupDir(backupCfg);
+  const src = path.join(dir, path.basename(backupFile)); // basename to prevent path traversal
+
+  if (!fs.existsSync(src)) {
+    return { success: false, message: `Backup file not found: ${backupFile}` };
+  }
+
+  if (DB_ENGINE === 'sqlite') {
+    const sqliteDb = db.getDb();
+    // better-sqlite3 exposes .name as the file path of the opened database
+    const dbPath = sqliteDb.name;
+    // Close, copy, re-open would require server restart — use SQLite's deserialization
+    // For simplicity, copy the backup over the current DB file
+    sqliteDb.close();
+    fs.copyFileSync(src, dbPath);
+    logger.info(`Restored backup: ${src} → ${dbPath}`);
+    return { success: true, message: `Database restored from ${backupFile}. Server restart may be required.` };
+  }
+
+  if (DB_ENGINE === 'postgres') {
+    const args = [
+      '-h', process.env.DB_HOST || 'localhost',
+      '-p', process.env.DB_PORT || '5432',
+      '-U', process.env.DB_USERNAME || 'postgres',
+      '-d', process.env.DB_DATABASE || 'manifest',
+      '-f', src,
+    ];
+    execFileSync('psql', args, {
+      env: { ...process.env, PGPASSWORD: process.env.DB_PASSWORD || 'postgres' },
+      timeout: 120000,
+    });
+    logger.info(`Restored backup: ${src}`);
+    return { success: true, message: `Database restored from ${backupFile}` };
+  }
+
+  if (DB_ENGINE === 'mysql') {
+    const content = fs.readFileSync(src, 'utf-8');
+    const args = [
+      '-h', process.env.DB_HOST || 'localhost',
+      '-P', process.env.DB_PORT || '3306',
+      '-u', process.env.DB_USERNAME || 'root',
+      process.env.DB_DATABASE || 'manifest',
+    ];
+    const env = { ...process.env };
+    if (process.env.DB_PASSWORD) env.MYSQL_PWD = process.env.DB_PASSWORD;
+    execFileSync('mysql', args, { env, input: content, timeout: 120000 });
+    logger.info(`Restored backup: ${src}`);
+    return { success: true, message: `Database restored from ${backupFile}` };
+  }
+
+  return { success: false, message: `Unsupported database engine: ${DB_ENGINE}` };
+}
+
+/**
+ * List available backups.
+ *
+ * @param {object|null} backupCfg  Value of `core.backup` (may be null).
+ * @returns {Array<{ file: string, size: number, createdAt: string }>}
+ */
+function listBackups(backupCfg) {
+  const dir = getBackupDir(backupCfg);
+  if (!fs.existsSync(dir)) return [];
+
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('backup-'))
+    .map((f) => {
+      const stats = fs.statSync(path.join(dir, f));
+      return { file: f, size: stats.size, createdAt: stats.mtime.toISOString() };
+    })
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt)); // newest first
+}
+
+module.exports = {
+  getBackupDir,
+  createBackup,
+  restoreBackup,
+  listBackups,
+};

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,
+};