pgserve 2.1.2 → 2.2.0

package/src/settings-validator.cjs

@@ -0,0 +1,416 @@
+/**
+ * Settings validator — shared between CLI (`autopg config set …`) and the
+ * UI helper (`PUT /api/settings`).
+ *
+ * Public surface:
+ *   - validateSetting(key, value, { schema? }) — single-leaf check, throws
+ *     ValidationError on failure.
+ *   - validateAll(settings, { schema? }) — full-tree check; throws on first
+ *     failure to keep error reporting deterministic for CLI (UI batches by
+ *     calling per-field on form blur).
+ *   - ValidationError — { code, field, message } shape, code is one of the
+ *     7 stable codes.
+ *   - ETAG_MISMATCH is exposed here so callers can `instanceof EtagMismatchError`
+ *     uniformly; the writer is the only producer.
+ *
+ * 7 error codes:
+ *   - INVALID_KEY       — key not in schema (and not under postgres._extra)
+ *   - INVALID_GUC_NAME  — postgres._extra.<name> failed GUC_NAME_REGEX
+ *   - INVALID_GUC_VALUE — postgres._extra.<name> value contains forbidden chars
+ *   - INVALID_TYPE      — value type doesn't match schema (e.g. string for int)
+ *   - OUT_OF_RANGE      — int/float value outside [min,max] or not in enum
+ *   - READONLY          — attempted write to a readonly-marked field
+ *   - ETAG_MISMATCH     — concurrent write detected (writer-side only)
+ */
+
+'use strict';
+
+const {
+  SCHEMA,
+  GUC_NAME_REGEX,
+  FORBIDDEN_VALUE_CHARS,
+  flattenSchema,
+} = require('./settings-schema.cjs');
+
+const ERROR_CODES = Object.freeze({
+  INVALID_KEY: 'INVALID_KEY',
+  INVALID_GUC_NAME: 'INVALID_GUC_NAME',
+  INVALID_GUC_VALUE: 'INVALID_GUC_VALUE',
+  INVALID_TYPE: 'INVALID_TYPE',
+  OUT_OF_RANGE: 'OUT_OF_RANGE',
+  READONLY: 'READONLY',
+  ETAG_MISMATCH: 'ETAG_MISMATCH',
+});
+
+class ValidationError extends Error {
+  constructor(code, field, message) {
+    super(`${field} — ${code}: ${message}`);
+    this.name = 'ValidationError';
+    this.code = code;
+    this.field = field;
+    this.detail = message;
+  }
+}
+
+class EtagMismatchError extends ValidationError {
+  constructor(currentEtag, providedEtag) {
+    super(
+      ERROR_CODES.ETAG_MISMATCH,
+      '_etag',
+      `expected ${providedEtag ?? '(none)'} but file has ${currentEtag}`,
+    );
+    this.name = 'EtagMismatchError';
+    this.currentEtag = currentEtag;
+    this.providedEtag = providedEtag;
+  }
+}
+
+/**
+ * Coerce a value into the descriptor's type when the input is a string
+ * (CLI argv path). `parse` is permissive; the caller should use the
+ * coerced value when persisting so `set` round-trips through `get`.
+ *
+ * Returns the coerced value or throws ValidationError(INVALID_TYPE).
+ */
+function coerce(field, descriptor, value) {
+  if (descriptor.type === 'guc_map') {
+    if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+    throw new ValidationError(
+      ERROR_CODES.INVALID_TYPE,
+      field,
+      `expected object map, got ${describe(value)}`,
+    );
+  }
+  if (descriptor.nullable && (value === null || value === '')) return value;
+
+  switch (descriptor.type) {
+    case 'int': {
+      if (typeof value === 'number' && Number.isInteger(value)) return value;
+      if (typeof value === 'string' && /^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+      }
+      throw new ValidationError(
+        ERROR_CODES.INVALID_TYPE,
+        field,
+        `expected integer, got ${describe(value)}`,
+      );
+    }
+    case 'bool': {
+      if (typeof value === 'boolean') return value;
+      if (value === 'true' || value === '1') return true;
+      if (value === 'false' || value === '0') return false;
+      throw new ValidationError(
+        ERROR_CODES.INVALID_TYPE,
+        field,
+        `expected boolean, got ${describe(value)}`,
+      );
+    }
+    case 'enum':
+    case 'string': {
+      if (typeof value === 'string') return value;
+      // Permit numbers + booleans → string for ergonomics (e.g.
+      // `config set ui.crt true`). The validator below enforces enum.
+      if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+      }
+      throw new ValidationError(
+        ERROR_CODES.INVALID_TYPE,
+        field,
+        `expected string, got ${describe(value)}`,
+      );
+    }
+    default:
+      // Unknown type: pass through. Caller's validateLeaf will fail
+      // with INVALID_KEY since this descriptor wouldn't be in the schema.
+      return value;
+  }
+}
+
+function describe(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+/**
+ * Validate a single leaf against its schema descriptor (already coerced).
+ * Throws ValidationError on failure; returns { ok: true, value } on success
+ * (value is the (possibly normalized) value to persist).
+ */
+function validateLeaf(field, descriptor, value) {
+  if (descriptor.readonly) {
+    throw new ValidationError(
+      ERROR_CODES.READONLY,
+      field,
+      'this field is read-only',
+    );
+  }
+  if (descriptor.nullable && (value === null || value === '')) {
+    return { ok: true, value };
+  }
+
+  switch (descriptor.type) {
+    case 'int': {
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_TYPE,
+          field,
+          `expected integer, got ${describe(value)}`,
+        );
+      }
+      if (descriptor.range) {
+        const [min, max] = descriptor.range;
+        if (value < min || value > max) {
+          throw new ValidationError(
+            ERROR_CODES.OUT_OF_RANGE,
+            field,
+            `value ${value} outside [${min}, ${max}]`,
+          );
+        }
+      }
+      // GUCs (curated ints) also pass through the value-char check below
+      // via toString during boot-time arg construction. Here we only check
+      // shape.
+      return { ok: true, value };
+    }
+    case 'bool': {
+      if (typeof value !== 'boolean') {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_TYPE,
+          field,
+          `expected boolean, got ${describe(value)}`,
+        );
+      }
+      return { ok: true, value };
+    }
+    case 'enum': {
+      if (typeof value !== 'string') {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_TYPE,
+          field,
+          `expected string, got ${describe(value)}`,
+        );
+      }
+      if (!descriptor.enum.includes(value)) {
+        throw new ValidationError(
+          ERROR_CODES.OUT_OF_RANGE,
+          field,
+          `must be one of [${descriptor.enum.join(', ')}], got "${value}"`,
+        );
+      }
+      assertScalarSafe(field, value);
+      return { ok: true, value };
+    }
+    case 'string': {
+      if (typeof value !== 'string') {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_TYPE,
+          field,
+          `expected string, got ${describe(value)}`,
+        );
+      }
+      // GUC string values are tightened (no \n/\r/\0, no leading -).
+      // Generic strings allow most characters but still ban nulls / newlines
+      // because they break our log line parsing.
+      assertScalarSafe(field, value, { strictGuc: !!descriptor.guc });
+      return { ok: true, value };
+    }
+    case 'guc_map': {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_TYPE,
+          field,
+          `expected object map, got ${describe(value)}`,
+        );
+      }
+      // Validate every (key, value) inside the passthrough map.
+      for (const [gucName, gucValue] of Object.entries(value)) {
+        validateExtraEntry(`${field}.${gucName}`, gucName, gucValue);
+      }
+      return { ok: true, value };
+    }
+    default:
+      throw new ValidationError(
+        ERROR_CODES.INVALID_KEY,
+        field,
+        `unknown schema type "${descriptor.type}"`,
+      );
+  }
+}
+
+/**
+ * Check a value for forbidden characters (\n / \r / \0) and, for GUC
+ * values, also reject a leading `-` (would look like a CLI flag to
+ * Bun.spawn array-form). Defense-in-depth alongside Bun.spawn's
+ * shell-bypass.
+ */
+function assertScalarSafe(field, value, { strictGuc = false } = {}) {
+  if (typeof value === 'number' || typeof value === 'boolean') return;
+  if (typeof value !== 'string') {
+    throw new ValidationError(
+      ERROR_CODES.INVALID_GUC_VALUE,
+      field,
+      `expected scalar primitive, got ${describe(value)}`,
+    );
+  }
+  if (FORBIDDEN_VALUE_CHARS.test(value)) {
+    throw new ValidationError(
+      ERROR_CODES.INVALID_GUC_VALUE,
+      field,
+      'value contains forbidden control character (\\n, \\r, or \\0)',
+    );
+  }
+  if (strictGuc && value.startsWith('-')) {
+    throw new ValidationError(
+      ERROR_CODES.INVALID_GUC_VALUE,
+      field,
+      'value must not start with "-" (looks like a CLI flag)',
+    );
+  }
+}
+
+/**
+ * Validate a single entry of `postgres._extra`. The key must match
+ * GUC_NAME_REGEX; the value must be a scalar primitive and pass the
+ * forbidden-char + leading-`-` checks.
+ */
+function validateExtraEntry(field, gucName, gucValue) {
+  if (typeof gucName !== 'string' || !GUC_NAME_REGEX.test(gucName)) {
+    throw new ValidationError(
+      ERROR_CODES.INVALID_GUC_NAME,
+      field,
+      `must match ${GUC_NAME_REGEX} (lowercase ASCII, starts with letter)`,
+    );
+  }
+  if (
+    typeof gucValue !== 'string' &&
+    typeof gucValue !== 'number' &&
+    typeof gucValue !== 'boolean'
+  ) {
+    throw new ValidationError(
+      ERROR_CODES.INVALID_GUC_VALUE,
+      field,
+      `expected scalar primitive, got ${describe(gucValue)}`,
+    );
+  }
+  assertScalarSafe(field, gucValue, { strictGuc: true });
+}
+
+/**
+ * Resolve a dotted key against the schema. Supports:
+ *   - server.port             → schema leaf
+ *   - postgres.shared_buffers → schema leaf
+ *   - postgres._extra         → the guc_map leaf
+ *   - postgres._extra.<name>  → dynamic entry under guc_map
+ *
+ * Returns { kind: 'leaf', descriptor } | { kind: 'extra-entry', gucName }
+ * or throws INVALID_KEY.
+ */
+function resolveKey(key, schema = SCHEMA) {
+  if (typeof key !== 'string' || !key.length) {
+    throw new ValidationError(ERROR_CODES.INVALID_KEY, String(key), 'empty key');
+  }
+  const parts = key.split('.');
+  if (parts.length === 2) {
+    const [section, field] = parts;
+    const descriptor = schema[section]?.[field];
+    if (!descriptor) {
+      throw new ValidationError(
+        ERROR_CODES.INVALID_KEY,
+        key,
+        `not in schema (section="${section}", field="${field}")`,
+      );
+    }
+    return { kind: 'leaf', descriptor };
+  }
+  if (parts.length === 3 && parts[0] === 'postgres' && parts[1] === '_extra') {
+    return { kind: 'extra-entry', gucName: parts[2] };
+  }
+  throw new ValidationError(
+    ERROR_CODES.INVALID_KEY,
+    key,
+    'unsupported key shape (only section.field or postgres._extra.<name>)',
+  );
+}
+
+/**
+ * Validate `value` against the descriptor for `key`. `value` may be a
+ * string (from CLI argv); we coerce per descriptor.type before the
+ * structural check.
+ */
+function validateSetting(key, value, { schema = SCHEMA } = {}) {
+  const resolved = resolveKey(key, schema);
+  if (resolved.kind === 'extra-entry') {
+    validateExtraEntry(key, resolved.gucName, value);
+    return { ok: true, value };
+  }
+  const coerced = coerce(key, resolved.descriptor, value);
+  return validateLeaf(key, resolved.descriptor, coerced);
+}
+
+/**
+ * Validate the entire settings tree. Throws on first failure for
+ * deterministic CLI error reporting.
+ */
+function validateAll(settings, { schema = SCHEMA } = {}) {
+  if (!settings || typeof settings !== 'object') {
+    throw new ValidationError(ERROR_CODES.INVALID_TYPE, '_root', 'settings must be an object');
+  }
+  for (const [section, fields] of Object.entries(schema)) {
+    const sectionValue = settings[section];
+    if (sectionValue === undefined) continue; // missing section → fall back to defaults later
+    if (!sectionValue || typeof sectionValue !== 'object') {
+      throw new ValidationError(
+        ERROR_CODES.INVALID_TYPE,
+        section,
+        `expected object, got ${describe(sectionValue)}`,
+      );
+    }
+    for (const [field, descriptor] of Object.entries(fields)) {
+      const dottedKey = `${section}.${field}`;
+      if (!(field in sectionValue)) continue;
+      validateLeaf(dottedKey, descriptor, sectionValue[field]);
+    }
+    // Reject unknown section keys to catch typos at write time.
+    for (const field of Object.keys(sectionValue)) {
+      if (!(field in fields)) {
+        throw new ValidationError(
+          ERROR_CODES.INVALID_KEY,
+          `${section}.${field}`,
+          `not in schema`,
+        );
+      }
+    }
+  }
+  // Reject unknown top-level sections.
+  for (const section of Object.keys(settings)) {
+    // Allow internal metadata keys (start with `_`) so we can store
+    // schema version markers without tripping the validator.
+    if (section.startsWith('_')) continue;
+    if (!(section in schema)) {
+      throw new ValidationError(
+        ERROR_CODES.INVALID_KEY,
+        section,
+        `not in schema`,
+      );
+    }
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  ERROR_CODES,
+  ValidationError,
+  EtagMismatchError,
+  validateSetting,
+  validateAll,
+  resolveKey,
+  // Test surface
+  _internals: {
+    coerce,
+    validateLeaf,
+    validateExtraEntry,
+    assertScalarSafe,
+    flattenSchema,
+  },
+};

package/src/settings-writer.cjs

@@ -0,0 +1,288 @@
+/**
+ * Settings writer — atomic, validated, chmod 0600, etag-aware.
+ *
+ * Public surface:
+ *   - writeSettings(newSettings, { ifMatch?, settingsPath? })
+ *       Validates, writes atomically (tmp + rename), chmod 0600, returns
+ *       the new etag.
+ *
+ *   - setLeaf(key, value, { ifMatch? }) → convenience for `autopg config set`.
+ *       Reads current settings, deep-merges the leaf, writes.
+ *
+ *   - removeExtra(gucName) → convenience for the UI's "delete row" action
+ *       inside `postgres._extra`.
+ *
+ * Concurrency model:
+ *   - On write: callers (UI helper) pass `ifMatch`. If the on-disk file
+ *     etag has drifted, we throw EtagMismatchError so the caller can
+ *     surface a "settings changed, reload?" banner instead of clobbering.
+ *   - CLI is single-process and skips ifMatch (each `set` is its own
+ *     transaction); callers may opt in by reading the loader etag first.
+ *
+ * File-mode invariant:
+ *   - Every successful write leaves `settings.json` at mode 0600 on
+ *     POSIX. On Windows, fs.chmodSync degrades gracefully (NTFS ACLs
+ *     would be the proper equivalent, out of scope for v1).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { SCHEMA, SCHEMA_VERSION, buildDefaults } = require('./settings-schema.cjs');
+const {
+  ValidationError,
+  EtagMismatchError,
+  validateAll,
+  validateSetting,
+} = require('./settings-validator.cjs');
+const {
+  computeEtag,
+  readSettingsFile,
+  getConfigDir,
+  getSettingsPath,
+  loadEffectiveConfig,
+} = require('./settings-loader.cjs');
+
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+/**
+ * Ensure the config directory exists with mode 0700. Idempotent.
+ * 0700 (vs 0755 in the legacy install path) because it now contains
+ * the password-bearing settings.json.
+ */
+function ensureConfigDir(configDir = getConfigDir()) {
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: DIR_MODE });
+    return;
+  }
+  // Best-effort tighten if it was created loose by an earlier wave.
+  try {
+    fs.chmodSync(configDir, DIR_MODE);
+  } catch {
+    // Non-POSIX or unowned dir — fall through; the file's own 0600 is
+    // the real defense.
+  }
+}
+
+/**
+ * Atomically write `bytes` to `targetPath`. Writes a sibling tmp file
+ * (same dir so rename is atomic on Linux/macOS), chmods it, then
+ * renames over the target.
+ */
+function atomicWrite(targetPath, bytes) {
+  const dir = path.dirname(targetPath);
+  const tmp = path.join(dir, `.${path.basename(targetPath)}.tmp.${process.pid}.${Date.now()}`);
+  // mode here only affects POSIX. Windows ignores it; we re-chmod after rename anyway.
+  fs.writeFileSync(tmp, bytes, { mode: FILE_MODE });
+  // Some filesystems (Linux ext4) require an explicit chmod after writeFileSync
+  // because umask can mask the mode bits.
+  try {
+    fs.chmodSync(tmp, FILE_MODE);
+  } catch {
+    // ignore on platforms that don't support chmod (Windows fallback)
+  }
+  fs.renameSync(tmp, targetPath);
+  // Re-chmod after rename in case the filesystem didn't preserve mode
+  // through the rename (rare but reported on some FUSE mounts).
+  try {
+    fs.chmodSync(targetPath, FILE_MODE);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Serialize the settings tree to deterministic JSON: section order
+ * follows SCHEMA, fields within a section follow SCHEMA, unknown keys
+ * (which validateAll already rejected) cannot appear here. Determinism
+ * is what makes the etag stable across UI re-saves of unchanged
+ * content.
+ */
+function serializeSettings(settings) {
+  const orderedSections = Object.keys(SCHEMA);
+  const out = { _schemaVersion: SCHEMA_VERSION };
+  // Carry forward `_`-prefixed top-level metadata (e.g. `_migratedFrom`)
+  // so migration markers and similar audit breadcrumbs survive a round-
+  // trip through the writer. validateAll already ignores these keys.
+  for (const [k, v] of Object.entries(settings)) {
+    if (k.startsWith('_') && k !== '_schemaVersion') out[k] = v;
+  }
+  for (const section of orderedSections) {
+    if (!settings[section]) continue;
+    out[section] = {};
+    for (const field of Object.keys(SCHEMA[section])) {
+      if (field in settings[section]) {
+        out[section][field] = settings[section][field];
+      }
+    }
+  }
+  return `${JSON.stringify(out, null, 2)}\n`;
+}
+
+/**
+ * Deep-merge `patch` into `base` (in place is fine since base is fresh
+ * each call). Arrays are replaced wholesale (not concatenated). Used
+ * to apply UI's partial PUT body on top of the current effective tree.
+ */
+function deepMerge(base, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return base;
+  for (const [key, value] of Object.entries(patch)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      base[key] &&
+      typeof base[key] === 'object' &&
+      !Array.isArray(base[key])
+    ) {
+      deepMerge(base[key], value);
+    } else {
+      base[key] = value;
+    }
+  }
+  return base;
+}
+
+/**
+ * Drop schema-internal helper fields from a settings tree (e.g. the
+ * `_schemaVersion` metadata we add on serialize) before re-validation.
+ * Validator's "unknown key" check ignores `_`-prefixed top-level keys
+ * but we strip on read for consistency.
+ */
+function stripMeta(settings) {
+  if (!settings || typeof settings !== 'object') return settings;
+  const { _schemaVersion, ...rest } = settings;
+  void _schemaVersion;
+  return rest;
+}
+
+/**
+ * Read current parsed settings from disk (or {}) and compute the etag
+ * the caller's `ifMatch` should be compared against.
+ */
+function readCurrent(settingsPath = getSettingsPath()) {
+  const { raw, parsed } = readSettingsFile(settingsPath);
+  return {
+    parsed: stripMeta(parsed) || {},
+    etag: computeEtag(raw),
+  };
+}
+
+/**
+ * Write the supplied (full) settings tree. Validates, atomically writes,
+ * chmods 0600, returns `{ etag }` of the new file. Throws ValidationError
+ * on shape/validation failure or EtagMismatchError on concurrency clash.
+ *
+ * `ifMatch` semantics:
+ *   - undefined → caller doesn't care (CLI). Skip the check.
+ *   - string    → compare against current on-disk etag; mismatch throws.
+ */
+function writeSettings(newSettings, { ifMatch, settingsPath = getSettingsPath() } = {}) {
+  if (!newSettings || typeof newSettings !== 'object') {
+    throw new ValidationError('INVALID_TYPE', '_root', 'expected object');
+  }
+
+  // Concurrency check first so we don't waste validation work when
+  // there's a race.
+  if (ifMatch !== undefined) {
+    const { etag: currentEtag } = readCurrent(settingsPath);
+    if (currentEtag !== ifMatch) {
+      throw new EtagMismatchError(currentEtag, ifMatch);
+    }
+  }
+
+  // Always validate the post-merge tree, not the patch — gives us a
+  // single source of truth for "what's about to land on disk".
+  const merged = stripMeta(newSettings);
+  validateAll(merged);
+
+  ensureConfigDir(path.dirname(settingsPath));
+  const bytes = serializeSettings(merged);
+  atomicWrite(settingsPath, bytes);
+
+  return { etag: computeEtag(Buffer.from(bytes, 'utf8')) };
+}
+
+/**
+ * Read current settings, apply a single-leaf update, and write back.
+ * Used by `autopg config set` and by validateSetting-aware UI flows.
+ *
+ * Supports:
+ *   - section.field            (curated leaf)
+ *   - postgres._extra.<gucName> (extra-entry; sets/replaces)
+ */
+function setLeaf(key, value, { ifMatch, settingsPath = getSettingsPath() } = {}) {
+  // Validate first so we never partially mutate on a bad input.
+  const { value: validated } = validateSetting(key, value);
+
+  // Read current settings tree (file-only, no env merge — the file is
+  // what we're editing). Defaults backfill missing sections so nesting
+  // works on a fresh install.
+  const { parsed: current } = readCurrent(settingsPath);
+  const baseline = buildDefaults();
+  const tree = deepMerge(baseline, current);
+
+  if (key.startsWith('postgres._extra.')) {
+    const gucName = key.slice('postgres._extra.'.length);
+    if (!tree.postgres) tree.postgres = {};
+    if (!tree.postgres._extra) tree.postgres._extra = {};
+    tree.postgres._extra[gucName] = validated;
+  } else {
+    const [section, field] = key.split('.');
+    if (!tree[section]) tree[section] = {};
+    tree[section][field] = validated;
+  }
+
+  return writeSettings(tree, { ifMatch, settingsPath });
+}
+
+/**
+ * Remove a key from `postgres._extra`. No-op if missing. Returns
+ * `{ etag }` of the new file (or current etag if no change was needed).
+ */
+function removeExtra(gucName, { ifMatch, settingsPath = getSettingsPath() } = {}) {
+  const { parsed: current } = readCurrent(settingsPath);
+  const tree = deepMerge(buildDefaults(), current);
+  if (tree.postgres?._extra && gucName in tree.postgres._extra) {
+    delete tree.postgres._extra[gucName];
+    return writeSettings(tree, { ifMatch, settingsPath });
+  }
+  return { etag: readCurrent(settingsPath).etag };
+}
+
+/**
+ * Initialize `settings.json` with schema defaults. Refuses to clobber
+ * an existing file unless `force: true`. Used by `autopg config init`.
+ */
+function initSettings({ force = false, settingsPath = getSettingsPath() } = {}) {
+  if (fs.existsSync(settingsPath) && !force) {
+    const err = new Error(
+      `${settingsPath} already exists; pass force=true to overwrite`,
+    );
+    err.code = 'EEXIST';
+    throw err;
+  }
+  return writeSettings(buildDefaults(), { settingsPath });
+}
+
+module.exports = {
+  writeSettings,
+  setLeaf,
+  removeExtra,
+  initSettings,
+  ensureConfigDir,
+  serializeSettings,
+  FILE_MODE,
+  DIR_MODE,
+  // Test surface
+  _internals: {
+    atomicWrite,
+    deepMerge,
+    stripMeta,
+    readCurrent,
+    loadEffectiveConfig,
+  },
+};