pgserve 2.1.2 → 2.2.0

package/src/postgres.js

@@ -19,6 +19,8 @@ import os from 'os';
 import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
+import { loadEffectiveConfig } from './settings-loader.cjs';
+import { buildPostgresArgs } from './settings-pg-args.cjs';
 
 /**
  * Get platform key for binary lookup (e.g., 'windows-x64', 'linux-x64', 'darwin-arm64')
@@ -38,12 +40,107 @@ function getPlatformKey() {
 }
 
 /**
- * Get the directory where extracted binaries are cached
+ * Pinned PostgreSQL major.minor.patch we expect in the cache. Bump alongside
+ * `package.json` `optionalDependencies.@embedded-postgres/*`. Used both as
+ * the download target AND as the cache-validity check — see `isCachedValid`.
+ */
+const PINNED_PG_VERSION = '18.3.0-beta.17';
+
+const VERSION_MARKER_FILENAME = '.version';
+
+/**
+ * Resolve the binary cache root, honouring the same env-var precedence
+ * as `getConfigDir()` in `src/cli-install.cjs`. Defaults to `~/.autopg/`
+ * (post-rename) so config and binary cache live in the same tree.
+ *
+ * Legacy `~/.pgserve/bin/<platform>` is migrated by `migrateLegacyBinaryCache`
+ * on first call; users with a 2.1.x cache still get a one-time move.
+ */
+function getAutopgRoot() {
+  return process.env.AUTOPG_CONFIG_DIR
+    || process.env.PGSERVE_CONFIG_DIR
+    || path.join(os.homedir(), '.autopg');
+}
+
+/**
+ * Get the directory where extracted binaries are cached.
  * @returns {string} Cache directory path
  */
 function getBinaryCacheDir() {
   const platformKey = getPlatformKey();
-  return path.join(os.homedir(), '.pgserve', 'bin', platformKey);
+  return path.join(getAutopgRoot(), 'bin', platformKey);
+}
+
+/**
+ * Read the cached version marker (the `.version` file) written next to
+ * the bin/lib trees on a successful extract. Returns the trimmed string
+ * or null when missing/unreadable.
+ */
+function readCachedVersion(cacheDir) {
+  try {
+    return fs.readFileSync(path.join(cacheDir, VERSION_MARKER_FILENAME), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the version marker after a successful extract so future cache
+ * checks can compare against `PINNED_PG_VERSION` and re-download when
+ * the package.json has bumped to a new release.
+ */
+function writeCachedVersion(cacheDir, version) {
+  try {
+    fs.writeFileSync(
+      path.join(cacheDir, VERSION_MARKER_FILENAME),
+      `${version}\n`,
+      { mode: 0o644 },
+    );
+  } catch {
+    // best-effort — failure here just means next boot re-downloads
+  }
+}
+
+/**
+ * Cache hit when BOTH:
+ *   - initdb + postgres exist in the bin/ subtree
+ *   - the `.version` marker matches `PINNED_PG_VERSION`
+ *
+ * The legacy presence-only check (no version marker) deliberately FAILS
+ * here so users carrying a pre-rename cache get a fresh, version-correct
+ * tree on the next daemon boot.
+ */
+function isCachedValid(cacheBinDir, expectedVersion) {
+  const platform = os.platform();
+  const initdbName = platform === 'win32' ? 'initdb.exe' : 'initdb';
+  const postgresName = platform === 'win32' ? 'postgres.exe' : 'postgres';
+  if (!fs.existsSync(path.join(cacheBinDir, initdbName))) return false;
+  if (!fs.existsSync(path.join(cacheBinDir, postgresName))) return false;
+  const cached = readCachedVersion(path.dirname(cacheBinDir));
+  return cached === expectedVersion;
+}
+
+/**
+ * One-time best-effort migration of `~/.pgserve/bin/<platform>` into the
+ * new `~/.autopg/bin/<platform>` location. We RENAME (atomic on the same
+ * fs) rather than copy to keep the operation cheap. On failure we fall
+ * back silently — the download path will recreate the cache.
+ */
+function migrateLegacyBinaryCache() {
+  const platformKey = getPlatformKey();
+  const newDir = getBinaryCacheDir();
+  if (fs.existsSync(newDir)) return;
+  const oldDir = path.join(os.homedir(), '.pgserve', 'bin', platformKey);
+  if (!fs.existsSync(oldDir)) return;
+  try {
+    fs.mkdirSync(path.dirname(newDir), { recursive: true });
+    fs.renameSync(oldDir, newDir);
+    console.log(`[pgserve] Migrated binary cache: ${oldDir} → ${newDir}`);
+  } catch (err) {
+    // EXDEV (cross-device) or permission errors fall through; the
+    // downloader will repopulate the new location.
+    console.log(`[pgserve] Could not migrate legacy binary cache (${err.code || err.message}); will re-download`);
+  }
 }
 
 /**
@@ -54,20 +151,32 @@ function getBinaryCacheDir() {
  */
 async function downloadPostgresBinaries() {
   const platform = os.platform();
+
+  // Carry over a legacy ~/.pgserve/bin cache the first time we run under
+  // the autopg path. After this, the new path is canonical.
+  migrateLegacyBinaryCache();
+
   const cacheDir = getBinaryCacheDir();
   const cacheBinDir = path.join(cacheDir, 'bin');
-  const initdbName = platform === 'win32' ? 'initdb.exe' : 'initdb';
-  const postgresName = platform === 'win32' ? 'postgres.exe' : 'postgres';
 
-  // Check if already downloaded
-  if (fs.existsSync(path.join(cacheBinDir, initdbName)) &&
-      fs.existsSync(path.join(cacheBinDir, postgresName))) {
+  // Cache hit: bin/initdb + bin/postgres present AND .version matches
+  // PINNED_PG_VERSION. Mismatch (e.g. user upgraded the npm package) or
+  // absence triggers a fresh download.
+  if (isCachedValid(cacheBinDir, PINNED_PG_VERSION)) {
     return cacheDir;
   }
 
+  const cachedVersion = readCachedVersion(cacheDir);
+  if (cachedVersion && cachedVersion !== PINNED_PG_VERSION) {
+    console.log(`[pgserve] Cached binaries are version ${cachedVersion}; pinned is ${PINNED_PG_VERSION} — re-downloading`);
+    // Wipe the stale tree before re-extracting to avoid mixing files
+    // from two different PG majors.
+    try { fs.rmSync(cacheDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+
   const platformKey = getPlatformKey();
   const pkgName = `@embedded-postgres/${platformKey}`;
-  const pkgVersion = '18.3.0-beta.17';
+  const pkgVersion = PINNED_PG_VERSION;
 
   console.log(`[pgserve] PostgreSQL binaries not found.`);
   console.log(`[pgserve] Downloading ${pkgName}@${pkgVersion}...`);
@@ -145,6 +254,10 @@ async function downloadPostgresBinaries() {
     // Ignore cleanup errors
   }
 
+  // Persist the version marker so the next boot can detect package-version
+  // bumps and re-download instead of silently running the old major.
+  writeCachedVersion(cacheDir, pkgVersion);
+
   console.log(`[pgserve] PostgreSQL binaries installed to ${cacheDir}`);
   return cacheDir;
 }
@@ -763,12 +876,22 @@ export class PostgresManager extends EventEmitter {
   async _startPostgres() {
     await this._ensureNoStalePostmasterLock();
     return new Promise((resolve, reject) => {
+      // Resolve effective postgres settings (defaults < ~/.autopg/settings.json
+      // < env). Curated GUCs land first; `postgres._extra` is layered in
+      // beneath them so curated values win on conflict. Invalid entries are
+      // dropped with a logger.warn — postgres still starts.
+      const { settings } = loadEffectiveConfig({ logger: this.logger });
+      const { args: gucArgs, applied: appliedGucs } = buildPostgresArgs(
+        settings.postgres,
+        { logger: this.logger },
+      );
+
       // Build PostgreSQL arguments
       const pgArgs = [
         this.binaries.postgres,
         '-D', this.databaseDir,
         '-p', this.port.toString(),
-        '-c', 'max_connections=1000',  // Support high connection counts for stress testing
+        ...gucArgs,
       ];
 
       // Enable Unix socket for faster local connections (Linux/macOS)
@@ -779,17 +902,16 @@ export class PostgresManager extends EventEmitter {
         pgArgs.push('-k', ''); // Disable Unix socket on Windows
       }
 
-      // Add logical replication settings when sync is enabled
-      // These settings enable PostgreSQL's native WAL-based replication
-      // with ZERO hot path impact (handled by PostgreSQL's WAL writer process)
-      if (this.syncEnabled) {
-        pgArgs.push(
-          '-c', 'wal_level=logical',           // Enable logical decoding
-          '-c', 'max_replication_slots=10',    // Support multiple subscriptions
-          '-c', 'max_wal_senders=10',          // Parallel replication streams
-          '-c', 'wal_keep_size=512MB',         // Retain WAL for catchup
+      // Surface the WAL block as an info log when sync is enabled, the same
+      // signal the previous hardcoded path emitted. The actual GUCs are now
+      // schema defaults (wal_level=logical, max_replication_slots=10,
+      // max_wal_senders=10, wal_keep_size=512MB) so they ship in `gucArgs`
+      // already — this log just preserves the operator-visible breadcrumb.
+      if (this.syncEnabled || settings.sync?.enabled) {
+        this.logger.info(
+          { walLevel: appliedGucs.wal_level },
+          'Logical replication enabled for sync',
         );
-        this.logger.info('Logical replication enabled for sync');
       }
 
       this.process = Bun.spawn(buildCommand(pgArgs, this.binaries.libDir), {

package/src/settings-loader.cjs

@@ -0,0 +1,235 @@
+/**
+ * Settings loader — reads `~/.autopg/settings.json`, merges defaults < file
+ * < env, returns `{ settings, sources, etag }`.
+ *
+ * Precedence:
+ *   default  (lowest)  — from settings-schema.js
+ *   file               — `~/.autopg/settings.json` (or AUTOPG_CONFIG_DIR override)
+ *   env      (highest) — process.env.AUTOPG_<X> beats process.env.PGSERVE_<X>
+ *
+ * `sources` is a flat map of dotted keys → 'default' | 'file' | 'env:<NAME>'.
+ * `etag` is sha256 of the raw file bytes (or 'sha256:empty' when no file
+ * exists). Deterministic for unchanged files, used for optimistic
+ * concurrency control on the UI helper's PUT path.
+ *
+ * The PGSERVE_<X>-only fall-through path emits a one-time deprecation
+ * note via `logger.warn` (suppressed on subsequent calls within the
+ * same process).
+ */
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { SCHEMA, buildDefaults } = require('./settings-schema.cjs');
+
+const SETTINGS_FILENAME = 'settings.json';
+const EMPTY_FILE_ETAG = 'sha256:empty';
+
+let _legacyEnvWarningEmitted = false;
+
+/**
+ * Where settings.json lives. AUTOPG_CONFIG_DIR wins over PGSERVE_CONFIG_DIR
+ * (the legacy var) which wins over the default `~/.autopg/`.
+ *
+ * NOTE: when only PGSERVE_CONFIG_DIR is set we fall back to `~/.pgserve/`
+ * (the legacy directory), not `~/.autopg/`. This is the migration-bridge
+ * path so existing operators keep working until they migrate. The migrate
+ * helper is what decouples the two.
+ */
+function getConfigDir() {
+  if (process.env.AUTOPG_CONFIG_DIR) return process.env.AUTOPG_CONFIG_DIR;
+  if (process.env.PGSERVE_CONFIG_DIR) return process.env.PGSERVE_CONFIG_DIR;
+  return path.join(os.homedir(), '.autopg');
+}
+
+function getSettingsPath() {
+  return path.join(getConfigDir(), SETTINGS_FILENAME);
+}
+
+/**
+ * Read raw file bytes and parse JSON. Returns `{ raw, parsed }` where
+ * `raw` is the bytes used to compute the etag and `parsed` is the JSON
+ * tree. Returns `{ raw: null, parsed: null }` when the file is missing.
+ *
+ * Throws SyntaxError when the file exists but doesn't parse — callers
+ * (CLI dispatch) should surface the path so operators can fix or
+ * re-init.
+ */
+function readSettingsFile(settingsPath = getSettingsPath()) {
+  if (!fs.existsSync(settingsPath)) return { raw: null, parsed: null };
+  const raw = fs.readFileSync(settingsPath);
+  try {
+    const parsed = JSON.parse(raw.toString('utf8'));
+    return { raw, parsed };
+  } catch (err) {
+    const wrapped = new SyntaxError(
+      `Failed to parse ${settingsPath}: ${err.message}`,
+    );
+    wrapped.cause = err;
+    wrapped.path = settingsPath;
+    throw wrapped;
+  }
+}
+
+/**
+ * Compute sha256 etag of the raw file bytes. Stable for unchanged
+ * files. `EMPTY_FILE_ETAG` for the missing-file case so callers can
+ * still pass an `If-Match` (and a CLI write that creates the file
+ * round-trips deterministically).
+ */
+function computeEtag(rawBytes) {
+  if (!rawBytes || rawBytes.length === 0) return EMPTY_FILE_ETAG;
+  const hash = crypto.createHash('sha256').update(rawBytes).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Cast an env var string into the descriptor's runtime type. Mirrors
+ * `coerce` in settings-validator but without throwing — env vars are
+ * trusted by definition (the operator set them) and any garbage value
+ * surfaces at runtime via the validator on the next write.
+ */
+function castEnv(descriptor, raw) {
+  switch (descriptor.type) {
+    case 'int': {
+      const n = Number.parseInt(raw, 10);
+      return Number.isFinite(n) ? n : descriptor.default;
+    }
+    case 'bool': {
+      if (raw === 'true' || raw === '1') return true;
+      if (raw === 'false' || raw === '0') return false;
+      return descriptor.default;
+    }
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Pick the env var that wins for a leaf, in priority order. Returns
+ * `{ envName, raw }` on hit, `null` on miss.
+ *
+ * The first AUTOPG_<X> that is set wins outright. Falling through to
+ * a PGSERVE_<X>-only setting trips the one-time deprecation note.
+ */
+function resolveEnv(descriptor, env, logger) {
+  if (!Array.isArray(descriptor.env) || descriptor.env.length === 0) return null;
+  for (const name of descriptor.env) {
+    if (env[name] !== undefined && env[name] !== '') {
+      const isLegacy = name.startsWith('PGSERVE_');
+      if (isLegacy && !_legacyEnvWarningEmitted) {
+        _legacyEnvWarningEmitted = true;
+        logger?.warn?.(
+          { env: name },
+          `${name} is deprecated; prefer ${descriptor.env[0]}`,
+        );
+      }
+      return { envName: name, raw: env[name] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Merge defaults < file < env, building up `sources` in lockstep so
+ * each leaf's origin is recorded. `postgres._extra` is treated
+ * specially: file value wins as a whole map (no per-key env overrides).
+ */
+function mergeWithSources({ defaults, fileSettings, env, logger, schema = SCHEMA }) {
+  const settings = {};
+  const sources = {};
+
+  for (const [section, fields] of Object.entries(schema)) {
+    settings[section] = {};
+    for (const [field, descriptor] of Object.entries(fields)) {
+      const dotted = `${section}.${field}`;
+      let value = clone(descriptor.default);
+      let source = 'default';
+
+      const fileSection = fileSettings && fileSettings[section];
+      if (fileSection && Object.prototype.hasOwnProperty.call(fileSection, field)) {
+        value = clone(fileSection[field]);
+        source = 'file';
+      }
+
+      const envHit = resolveEnv(descriptor, env, logger);
+      if (envHit) {
+        value = castEnv(descriptor, envHit.raw);
+        source = `env:${envHit.envName}`;
+      }
+
+      settings[section][field] = value;
+      sources[dotted] = source;
+    }
+  }
+  return { settings, sources };
+}
+
+function clone(value) {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(clone);
+  const out = {};
+  for (const [k, v] of Object.entries(value)) out[k] = clone(v);
+  return out;
+}
+
+/**
+ * Load + merge entry point. Returns `{ settings, sources, etag, path }`.
+ *
+ * `logger` is optional — when omitted, deprecation notes go to
+ * stderr via console.warn so the CLI surface still has visibility.
+ *
+ * `env` defaults to process.env so callers can inject a frozen snapshot
+ * for tests.
+ */
+function loadEffectiveConfig({
+  schema = SCHEMA,
+  env = process.env,
+  logger,
+  settingsPath = getSettingsPath(),
+} = {}) {
+  const fallbackLogger = logger || {
+    warn: (data, msg) => console.warn(`[autopg] ${msg ?? ''} ${JSON.stringify(data ?? {})}`),
+  };
+  const { raw, parsed } = readSettingsFile(settingsPath);
+  const defaults = buildDefaults(schema);
+  const { settings, sources } = mergeWithSources({
+    defaults,
+    fileSettings: parsed,
+    env,
+    logger: fallbackLogger,
+    schema,
+  });
+  const etag = computeEtag(raw);
+  return { settings, sources, etag, path: settingsPath };
+}
+
+/**
+ * Test helper: reset the once-flag so multiple test cases can each
+ * observe the deprecation log line.
+ */
+function resetLegacyEnvWarning() {
+  _legacyEnvWarningEmitted = false;
+}
+
+module.exports = {
+  loadEffectiveConfig,
+  computeEtag,
+  readSettingsFile,
+  getConfigDir,
+  getSettingsPath,
+  EMPTY_FILE_ETAG,
+  SETTINGS_FILENAME,
+  // Test surface
+  _internals: {
+    castEnv,
+    resolveEnv,
+    mergeWithSources,
+    resetLegacyEnvWarning,
+  },
+};

package/src/settings-migrate.cjs

@@ -0,0 +1,212 @@
+/**
+ * One-shot migration from `~/.pgserve/` to `~/.autopg/`.
+ *
+ * Trigger: dispatcher pre-flight on every CLI entry point.
+ * Behavior:
+ *   - If `~/.autopg/` already exists OR `~/.pgserve/` does not exist → no-op.
+ *   - Else: copy the legacy directory contents to `~/.autopg/` preserving
+ *     mtimes, then drop `MIGRATED-FROM-PGSERVE.md` in the old dir as the
+ *     idempotency marker.
+ *   - Skips if the marker already exists, even if the new dir was later
+ *     deleted (so the migration is permanent — operators who want to redo
+ *     it must remove the marker manually).
+ *
+ * The legacy dir is left in place (not removed) so operators can A/B and
+ * roll back if anything goes wrong. This is intentional: this code runs
+ * unattended on every `autopg <subcommand>` invocation, so we err on the
+ * side of preserving the user's data.
+ *
+ * The migration also normalizes the legacy `config.json` (just port +
+ * dataDir + registeredAt) into the new `settings.json` shape: the legacy
+ * fields populate `server.port` and `runtime.dataDir`, everything else is
+ * filled with defaults.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { buildDefaults, SCHEMA_VERSION } = require('./settings-schema.cjs');
+const { serializeSettings } = require('./settings-writer.cjs');
+
+const MARKER_FILENAME = 'MIGRATED-FROM-PGSERVE.md';
+const MARKER_BODY = `# Migrated to ~/.autopg/
+
+This directory has been migrated to \`~/.autopg/\` as part of the
+soft-rename to autopg. Settings, data, and logs were copied verbatim;
+the legacy location is preserved so you can roll back if needed.
+
+To complete the cutover (after verifying autopg works):
+
+    rm -rf ~/.pgserve
+
+This file is the migration's idempotency marker — its presence prevents
+re-migration on subsequent autopg invocations.
+`;
+
+/**
+ * Resolve the legacy and new config directories.
+ *
+ * Migration only runs against the *default* `~/.pgserve` → `~/.autopg`
+ * pair. When the user has either env override set, they're in
+ * custom-config-dir mode (CI, tests, multi-instance setups) and we
+ * never auto-migrate — that's a foot-gun. Operators in custom mode
+ * who want to migrate can:
+ *
+ *   1. unset AUTOPG_CONFIG_DIR/PGSERVE_CONFIG_DIR
+ *   2. run `autopg config init`
+ *   3. copy whatever they need by hand
+ *
+ * The override-skip path is the reason `legacy`/`fresh` may be null
+ * here; `migrateIfNeeded` short-circuits in that case.
+ *
+ * Tests opt in to the default-path flow by passing an explicit `home`
+ * (a tempdir) instead of relying on env vars.
+ */
+function resolveDirs({ home = os.homedir(), env = process.env, allowOverrides = false } = {}) {
+  if (!allowOverrides && (env.AUTOPG_CONFIG_DIR || env.PGSERVE_CONFIG_DIR)) {
+    return { legacy: null, fresh: null, skipped: true };
+  }
+  const legacy = path.join(home, '.pgserve');
+  const fresh = path.join(home, '.autopg');
+  return { legacy, fresh };
+}
+
+/**
+ * Top-level directory names under the legacy `~/.pgserve/` that we DON'T
+ * carry over during the soft-rename migration:
+ *
+ *   - `bin/`  — embedded-postgres binary cache, ~120 MB. Postgres binaries
+ *               are version-specific; the new daemon re-fetches the pinned
+ *               version on first boot via the version-aware cache check
+ *               in `src/postgres.js`. Copying defeats that AND wastes disk.
+ *
+ * Persistent `data/` and pm2 `logs/` ARE migrated — users with stateful
+ * setups expect them to survive the rename.
+ */
+const LEGACY_SKIP_TOPLEVEL = new Set(['bin']);
+
+/**
+ * Recursively copy `src` to `dest` preserving mtimes. Skips the marker
+ * file (so a re-migration after marker removal doesn't carry it over)
+ * and skips any path under `dest` that already exists (we never
+ * overwrite during migration). At the top level, also skips the
+ * heavy/version-specific directories listed in `LEGACY_SKIP_TOPLEVEL`.
+ */
+function copyTree(src, dest, depth = 0) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
+
+  for (const entry of entries) {
+    if (entry.name === MARKER_FILENAME) continue;
+    if (depth === 0 && LEGACY_SKIP_TOPLEVEL.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath, depth + 1);
+    } else if (entry.isFile()) {
+      if (fs.existsSync(destPath)) continue;
+      fs.copyFileSync(srcPath, destPath);
+      const stat = fs.statSync(srcPath);
+      try {
+        fs.utimesSync(destPath, stat.atime, stat.mtime);
+      } catch {
+        // best-effort; don't fail migration over an mtime preserve hiccup
+      }
+    }
+    // Symlinks / sockets are skipped; the legacy dir never contains them.
+  }
+}
+
+/**
+ * Translate the legacy `config.json` shape ({ port, dataDir, registeredAt })
+ * into the new `settings.json` shape, filling everything else with defaults.
+ *
+ * Returns the serialized JSON string ready to write.
+ */
+function buildSettingsFromLegacyConfig(legacyConfig) {
+  const tree = buildDefaults();
+  if (legacyConfig && typeof legacyConfig === 'object') {
+    if (Number.isInteger(legacyConfig.port)) {
+      tree.server.port = legacyConfig.port;
+    }
+    if (typeof legacyConfig.dataDir === 'string' && legacyConfig.dataDir.length) {
+      tree.runtime.dataDir = legacyConfig.dataDir;
+    }
+  }
+  // Marker the migration even within the file payload so a future
+  // dump-with-context tool can identify it.
+  tree._migratedFrom = '~/.pgserve';
+  tree._schemaVersion = SCHEMA_VERSION;
+  return serializeSettings(tree);
+}
+
+/**
+ * Run the migration. Idempotent — safe to call from the dispatcher
+ * pre-flight on every command. Returns `{ migrated: bool, reason }`
+ * for callers (and tests) that want to log the outcome.
+ */
+function migrateIfNeeded(opts = {}) {
+  const dirs = resolveDirs(opts);
+  if (dirs.skipped) {
+    return { migrated: false, reason: 'env-override-set', ...dirs };
+  }
+  const { legacy, fresh } = dirs;
+  const markerPath = path.join(legacy, MARKER_FILENAME);
+
+  if (!fs.existsSync(legacy)) {
+    return { migrated: false, reason: 'no-legacy-dir', legacy, fresh };
+  }
+  if (fs.existsSync(markerPath)) {
+    return { migrated: false, reason: 'already-migrated', legacy, fresh };
+  }
+  if (fs.existsSync(fresh)) {
+    // Both exist, no marker — operator may have created `~/.autopg/`
+    // independently. Don't touch either; leave the marker in place so
+    // we don't try again.
+    fs.writeFileSync(markerPath, MARKER_BODY, { mode: 0o644 });
+    return { migrated: false, reason: 'both-exist-marker-set', legacy, fresh };
+  }
+
+  // Copy the directory tree first so any failure leaves the legacy
+  // dir untouched.
+  copyTree(legacy, fresh);
+
+  // Translate config.json → settings.json if present and the new file
+  // wasn't already created via copyTree (which would have copied any
+  // existing settings.json verbatim).
+  const legacyConfigPath = path.join(legacy, 'config.json');
+  const freshSettingsPath = path.join(fresh, 'settings.json');
+  if (fs.existsSync(legacyConfigPath) && !fs.existsSync(freshSettingsPath)) {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(fs.readFileSync(legacyConfigPath, 'utf8'));
+    } catch {
+      parsed = null;
+    }
+    const bytes = buildSettingsFromLegacyConfig(parsed);
+    fs.writeFileSync(freshSettingsPath, bytes, { mode: 0o600 });
+    try {
+      fs.chmodSync(freshSettingsPath, 0o600);
+    } catch {
+      // ignore on platforms without chmod support
+    }
+  }
+
+  fs.writeFileSync(markerPath, MARKER_BODY, { mode: 0o644 });
+  return { migrated: true, reason: 'copied', legacy, fresh };
+}
+
+module.exports = {
+  migrateIfNeeded,
+  resolveDirs,
+  buildSettingsFromLegacyConfig,
+  MARKER_FILENAME,
+  MARKER_BODY,
+  // Test surface
+  _internals: {
+    copyTree,
+  },
+};