influx-local-cli 0.1.0

package/src/manager.js

@@ -0,0 +1,1794 @@
+'use strict';
+
+const fs = require('fs/promises');
+const path = require('path');
+const os = require('os');
+const net = require('net');
+const { spawn } = require('child_process');
+const configMod = require('./config');
+const {
+  loadConfig,
+  saveMiseToml,
+  readCreds,
+  writeCreds,
+  randomPassword,
+  randomToken,
+  miseBin,
+} = configMod;
+const { flavorOf, artifactsFor, assertIdentifier } = require('./versions');
+
+const noopLog = () => {};
+
+// --- Low-level process helpers ---------------------------------------------
+
+// Spawn a command, capturing stdout/stderr. Resolves {code, stdout, stderr}.
+function spawnOut(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        env: { ...baseEnv(), ...(opts.env || {}) },
+        cwd: opts.cwd,
+        windowsHide: true,
+      });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const out = [];
+    const errOut = [];
+    child.stdout.on('data', (d) => out.push(d));
+    child.stderr.on('data', (d) => errOut.push(d));
+    child.on('error', (err) => reject(err));
+    child.on('close', (code) =>
+      resolve({ code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(errOut).toString('utf8') }),
+    );
+  });
+}
+
+function errText(msg, res) {
+  const detail = (res.stderr || '').trim() || (res.stdout || '').trim();
+  return detail ? `${msg}: ${detail}` : msg;
+}
+
+// Environment for every child process: the user's own InfluxDB variables are
+// stripped so an exported INFLUXDB_HTTP_BIND_ADDRESS / INFLUX_TOKEN cannot leak
+// into an instance we manage.
+function baseEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (/^INFLUX(_LOCAL)?(_|$)|^INFLUXDB|^INFLUXD/.test(key)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function pidAlive(pid) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM'; // exists but owned by someone else
+  }
+}
+
+async function readPidFile(pidPath) {
+  try {
+    const data = (await fs.readFile(pidPath, 'utf8')).trim();
+    const pid = parseInt(data, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+// True when something is already listening on host:port.
+function checkPort(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(true));
+    server.listen(port, host, () => {
+      server.close(() => resolve(false));
+    });
+  });
+}
+
+// Probe address that matches how the instance binds (0.0.0.0 listens on
+// 127.0.0.1 as well).
+function probeHost(cfg) {
+  return cfg.host === '0.0.0.0' || cfg.host === '::' ? '127.0.0.1' : cfg.host || '127.0.0.1';
+}
+
+function httpBase(cfg, { boot = false } = {}) {
+  return `http://${boot ? '127.0.0.1' : probeHost(cfg)}:${cfg.port}`;
+}
+
+async function instancePortBound(cfg) {
+  return checkPort(cfg.port, probeHost(cfg));
+}
+
+async function waitBound(cfg, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await instancePortBound(cfg)) return true;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return false;
+}
+
+// HTTP probe with a hard timeout; never throws.
+async function httpProbe(url, { headers = {}, timeoutMs = 2500 } = {}) {
+  try {
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs), redirect: 'manual' });
+    let body = null;
+    try {
+      body = await res.text();
+    } catch (err) {
+      body = null;
+    }
+    return { status: res.status, body };
+  } catch (err) {
+    return { status: 0, body: null, error: err };
+  }
+}
+
+async function httpJson(url, opts = {}) {
+  const res = await httpProbe(url, opts);
+  if (!res.body) return { status: res.status, json: null };
+  try {
+    return { status: res.status, json: JSON.parse(res.body) };
+  } catch (err) {
+    return { status: res.status, json: null, body: res.body };
+  }
+}
+
+function basicAuth(user, password) {
+  return `Basic ${Buffer.from(`${user}:${password}`).toString('base64')}`;
+}
+
+// Wait until the server answers on /ping (1.x) or /health (2.x/3.x).
+// `accept` lists the statuses that mean "up": InfluxDB 3 answers 401 on
+// /health until a token is presented, which still proves the server is up.
+async function waitReady(cfg, { boot = false, timeoutMs = 30000, pollMs = 400, accept } = {}) {
+  const url = `${httpBase(cfg, { boot })}${cfg.flavor === 'v1' ? '/ping' : '/health'}`;
+  const ok = accept || (cfg.flavor === 'v1' ? [204, 200] : cfg.flavor === 'v2' ? [200] : [200, 401, 403]);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await httpProbe(url);
+    if (ok.includes(res.status)) return true;
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return false;
+}
+
+async function waitPortFree(cfg, { timeoutMs = 15000, pollMs = 200 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!(await checkPort(cfg.port, probeHost(cfg)))) return true;
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return false;
+}
+
+// --- Toolchain (mise) -------------------------------------------------------
+
+// One binary path per executable name, resolved through mise's install dir for
+// this instance's pinned version. Cached per (instance dir, version) so a long
+// running web dashboard does not re-shell out for every operation.
+const binCache = new Map();
+
+function clearBinCache(cfg) {
+  for (const key of [...binCache.keys()]) {
+    if (key.startsWith(`${cfg.instanceDir}::`)) binCache.delete(key);
+  }
+}
+
+// Environment for every mise invocation. Two things matter:
+//   MISE_CEILING_PATHS      stops the config search at the instance dir, so an
+//                           unrelated (and untrusted) .mise.toml in $HOME or
+//                           any parent directory cannot abort the call with
+//                           "Config files ... are not trusted".
+//   MISE_TRUSTED_CONFIG_PATHS trusts the .mise.toml we generate per instance.
+function miseEnv(cfg) {
+  return {
+    MISE_CEILING_PATHS: cfg.instanceDir,
+    MISE_TRUSTED_CONFIG_PATHS: cfg.instanceDir,
+  };
+}
+
+async function resolveBins(cfg, { require = true } = {}) {
+  const cacheKey = `${cfg.instanceDir}::${cfg.version}`;
+  const cached = binCache.get(cacheKey);
+  if (cached) return cached;
+
+  const found = {};
+  const problems = [];
+  for (const artifact of artifactsFor(cfg.version)) {
+    const version = artifact.artifactVersion || cfg.version;
+    const res = await spawnOut(miseBin(), ['where', '-C', cfg.instanceDir, `http:${artifact.tool}@${version}`], {
+      env: miseEnv(cfg),
+    });
+    const dir = res.stdout.trim();
+    if (res.code !== 0 || !dir) {
+      const detail = (res.stderr || res.stdout || '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !/^mise (ERROR )?(Version:|Run with)/.test(line))
+        .slice(-3)
+        .join(' ');
+      problems.push(`mise where http:${artifact.tool}@${version} failed (exit ${res.code})${detail ? `: ${detail}` : ''}`);
+      continue;
+    }
+    for (const exe of artifact.exe) {
+      if (found[exe]) continue;
+      const resolved = await findExecutable(dir, exe);
+      if (resolved) found[exe] = resolved;
+      else problems.push(`"${exe}" not found under ${dir}`);
+    }
+  }
+  if (require && !found[cfg.serverBin]) {
+    throw new Error(
+      `InfluxDB ${cfg.version} is not installed for "${cfg.name}" — run "influx-local install ${cfg.name}" first` +
+        (problems.length ? `\n  ${problems.join('\n  ')}` : ''),
+    );
+  }
+  binCache.set(cacheKey, found);
+  return found;
+}
+
+async function findExecutable(root, name, maxDepth = 5) {
+  const queue = [{ dir: root, depth: 0 }];
+  while (queue.length) {
+    const { dir, depth } = queue.shift();
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < maxDepth) queue.push({ dir: full, depth: depth + 1 });
+      } else if (entry.name === name) {
+        try {
+          await fs.access(full, fs.constants.X_OK);
+          return full;
+        } catch (err) {
+          // not executable
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// Install (idempotent) the instance's pinned version through mise.
+async function installTools(cfg, log = noopLog) {
+  log(`installing InfluxDB ${cfg.version} (${cfg.flavorLabel}) via ${miseBin()}…`);
+  await saveMiseToml(cfg.name, cfg.version);
+  const res = await spawnOut(miseBin(), ['install', '-C', cfg.instanceDir], { env: miseEnv(cfg) });
+  if (res.code !== 0) {
+    throw new Error(errText(`failed to install InfluxDB ${cfg.version}`, res));
+  }
+  clearBinCache(cfg);
+  const bins = await resolveBins(cfg);
+  const list = Object.entries(bins).map(([exe, p]) => `${exe} → ${p}`).join(', ');
+  log(`toolchain ready: ${list}`);
+  return bins;
+}
+
+// Run an InfluxDB binary (resolved through mise) with our environment.
+async function runBin(cfg, exe, args, opts = {}) {
+  const bins = opts.bins || (await resolveBins(cfg));
+  const bin = bins[exe];
+  if (!bin) {
+    throw new Error(`"${exe}" is not installed for "${cfg.name}" — run "influx-local install ${cfg.name}"`);
+  }
+  return spawnOut(bin, args, { env: { ...cliEnv(cfg), ...(opts.env || {}) }, cwd: opts.cwd });
+}
+
+// InfluxDB 2.x's CLI stores host/token/org shortcuts in a config file; keep it
+// inside the instance dir instead of the user's ~/.influxdbv2/configs.
+function cliEnv(cfg) {
+  if (cfg.flavor === 'v2') return { INFLUX_CONFIGS_PATH: cfg.cliConfigsPath };
+  return {};
+}
+
+// --- Daemon lifecycle -------------------------------------------------------
+
+function bindAddress(cfg) {
+  return `${cfg.host}:${cfg.port}`;
+}
+
+function daemonArgs(cfg, { boot = false } = {}) {
+  if (cfg.flavor === 'v1') {
+    // 1.x is configured entirely through INFLUXDB_* environment variables.
+    return [];
+  }
+  if (cfg.flavor === 'v2') {
+    return [
+      '--bolt-path', path.join(cfg.dataDir, 'influxd.bolt'),
+      '--engine-path', path.join(cfg.dataDir, 'engine'),
+      '--http-bind-address', boot ? `127.0.0.1:${cfg.port}` : bindAddress(cfg),
+      '--reporting-disabled',
+    ];
+  }
+  // InfluxDB 3 Core: a single binary with a `serve` subcommand.
+  return [
+    'serve',
+    '--node-id', nodeId(cfg),
+    '--object-store', 'file',
+    '--data-dir', cfg.dataDir,
+    '--http-bind', boot ? `127.0.0.1:${cfg.port}` : bindAddress(cfg),
+  ];
+}
+
+// 3 Core uses the node id as a prefix in object-store paths.
+function nodeId(cfg) {
+  return cfg.name.replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+function daemonEnv(cfg, { boot = false, withoutAuth = false } = {}) {
+  if (cfg.flavor !== 'v1') return {};
+  return {
+    INFLUXDB_META_DIR: path.join(cfg.dataDir, 'meta'),
+    INFLUXDB_DATA_DIR: path.join(cfg.dataDir, 'data'),
+    INFLUXDB_DATA_WAL_DIR: path.join(cfg.dataDir, 'wal'),
+    INFLUXDB_HTTP_BIND_ADDRESS: boot ? `127.0.0.1:${cfg.port}` : bindAddress(cfg),
+    INFLUXDB_HTTP_AUTH_ENABLED: withoutAuth || boot ? 'false' : 'true',
+    INFLUXDB_REPORTING_DISABLED: 'true',
+  };
+}
+
+async function ensureDirs(cfg) {
+  await fs.mkdir(cfg.dataDir, { recursive: true });
+  if (cfg.flavor === 'v2') await fs.mkdir(path.join(cfg.dataDir, 'engine'), { recursive: true });
+  await fs.mkdir(path.dirname(cfg.logPath), { recursive: true });
+}
+
+// Fork the server so it outlives this CLI: detached, stdio to the instance log,
+// pid recorded by us (InfluxDB has no --fork/--pidfile).
+async function spawnDaemon(cfg, { boot = false, withoutAuth = false, log = noopLog } = {}) {
+  const bins = await resolveBins(cfg);
+  await ensureDirs(cfg);
+  const logPath = boot ? cfg.bootLogPath : cfg.logPath;
+  const pidPath = boot ? cfg.bootPidPath : cfg.pidPath;
+  const args = daemonArgs(cfg, { boot });
+  if (withoutAuth && cfg.flavor === 'v3') args.push('--without-auth');
+  const env = { ...baseEnv(), ...daemonEnv(cfg, { boot, withoutAuth }) };
+
+  log(args.length ? `${cfg.serverBin} ${args.join(' ')}` : `starting ${cfg.serverBin}`);
+  const handle = await fs.open(logPath, 'a');
+  let child;
+  try {
+    child = spawn(bins[cfg.serverBin], args, {
+      detached: true,
+      stdio: ['ignore', handle.fd, handle.fd],
+      env,
+    });
+  } finally {
+    await handle.close();
+  }
+  child.unref();
+
+  const failed = await new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    child.once('error', (err) => done(err));
+    child.once('exit', (code, signal) => done({ code, signal }));
+    setTimeout(() => done(null), 400);
+  });
+
+  if (failed) {
+    const tail = await logTail(logPath, 20);
+    const detail = failed instanceof Error ? failed.message : `exited with code ${failed.code}${failed.signal ? ` (${failed.signal})` : ''}`;
+    throw new Error(`${cfg.serverBin} failed to start (${detail})${tail ? `\n  ${path.basename(logPath)} tail:\n${tail}` : ''}`);
+  }
+  await fs.writeFile(pidPath, String(child.pid));
+  log(`${cfg.serverBin} started (pid ${child.pid})`);
+  return child.pid;
+}
+
+// Last `lines` of a log file (best effort, capped read).
+async function logTail(logPath, lines = 15) {
+  try {
+    const stat = await fs.stat(logPath);
+    if (!stat.isFile() || stat.size === 0) return '';
+    const chunk = Math.min(64 * 1024, stat.size);
+    const handle = await fs.open(logPath, 'r');
+    const buf = Buffer.alloc(chunk);
+    let text = '';
+    try {
+      const { bytesRead } = await handle.read(buf, 0, chunk, Math.max(0, stat.size - chunk));
+      text = buf.slice(0, bytesRead).toString('utf8');
+    } finally {
+      await handle.close();
+    }
+    return text.split(/\r?\n/).filter(Boolean).slice(-lines).join('\n');
+  } catch (err) {
+    return '';
+  }
+}
+
+async function stopPid(pid, { force = false, log = noopLog, name = 'server' } = {}) {
+  if (!pid || !pidAlive(pid)) return;
+  log(`stopping ${name} (pid ${pid})…`);
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    // already gone
+  }
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline && pidAlive(pid)) {
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  if (pidAlive(pid)) {
+    if (!force) {
+      throw new Error(`${name} (pid ${pid}) did not stop in time — re-run with --force to kill it`);
+    }
+    log('terminating forcefully (SIGKILL)…');
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch (err) {}
+    await new Promise((r) => setTimeout(r, 1000));
+    if (pidAlive(pid)) throw new Error(`${name} (pid ${pid}) survived SIGKILL`);
+  }
+}
+
+async function stopDaemon(cfg, { force = false, pidPath, log = noopLog } = {}) {
+  const target = pidPath || cfg.pidPath;
+  const pid = await readPidFile(target);
+  if (!pid || !pidAlive(pid)) return false;
+  await stopPid(pid, { force, log, name: cfg.serverBin });
+  await fs.rm(target, { force: true }).catch(() => {});
+  return true;
+}
+
+// --- Credentials ------------------------------------------------------------
+
+// Fresh credentials in the shape the instance's auth model needs.
+function freshCreds(cfg) {
+  if (cfg.flavor === 'v1') {
+    return {
+      ADMIN_USER: cfg.adminUser,
+      ADMIN_PW: randomPassword(),
+      APP_USER: cfg.appUser,
+      APP_PW: randomPassword(),
+    };
+  }
+  if (cfg.flavor === 'v2') {
+    // The token is minted by the server during onboarding; the placeholder is
+    // replaced by whatever value the operator token ends up with.
+    return {
+      ADMIN_USER: cfg.adminUser,
+      ADMIN_PW: randomPassword(),
+      ADMIN_TOKEN: randomToken(),
+      APP_TOKEN: '',
+      ORG: cfg.org,
+      BUCKET: cfg.database,
+    };
+  }
+  return { ADMIN_TOKEN: '' }; // 3 Core mints its admin token on first setup
+}
+
+async function resolveCreds(cfg, log = noopLog) {
+  let creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) {
+    creds = freshCreds(cfg);
+    if (cfg.flavor !== 'v3') {
+      await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+      log(`generated new credentials -> ${cfg.credsPath} (mode 0600)`);
+    }
+    return creds;
+  }
+  // Keep identifiers in sync with config (a renamed user/org/database/bucket).
+  let changed = false;
+  const sync = (field, value) => {
+    if (value && creds[field] !== value) {
+      creds[field] = value;
+      changed = true;
+    }
+  };
+  if (cfg.flavor === 'v1') {
+    sync('ADMIN_USER', cfg.adminUser);
+    sync('APP_USER', cfg.appUser);
+  } else if (cfg.flavor === 'v2') {
+    sync('ADMIN_USER', cfg.adminUser);
+    sync('ORG', cfg.org);
+    sync('BUCKET', cfg.database);
+  }
+  if (changed) await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+  return creds;
+}
+
+// --- v1: InfluxQL users / databases ----------------------------------------
+
+function sqlString(value) {
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function ident(name) {
+  return `"${String(name).replace(/"/g, '\\"')}"`;
+}
+
+function v1BaseArgs(cfg, { boot = false, creds = null, admin = false, database = null, format = 'json' } = {}) {
+  const args = ['-host', boot ? '127.0.0.1' : probeHost(cfg), '-port', String(cfg.port)];
+  if (creds) {
+    args.push('-username', admin ? creds.ADMIN_USER : creds.APP_USER);
+    args.push('-password', admin ? creds.ADMIN_PW : creds.APP_PW);
+  }
+  if (database) args.push('-database', database);
+  if (format) args.push('-format', format);
+  return args;
+}
+
+async function v1Query(cfg, statement, opts = {}) {
+  const args = [...v1BaseArgs(cfg, opts), '-execute', statement];
+  const res = await runBin(cfg, cfg.cliBin, args, opts);
+  if (res.code !== 0) {
+    throw new Error(errText(`InfluxQL statement failed: ${statement}`, res));
+  }
+  const text = res.stdout.trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return {};
+  }
+}
+
+// Flatten InfluxQL JSON results into rows of plain values.
+function v1Rows(json) {
+  const rows = [];
+  for (const result of (json && json.results) || []) {
+    for (const series of result.series || []) {
+      for (const values of series.values || []) rows.push(values);
+    }
+  }
+  return rows;
+}
+
+async function v1Show(cfg, statement, opts = {}) {
+  const rows = v1Rows(await v1Query(cfg, statement, opts));
+  return rows.map((row) => row[0]);
+}
+
+async function v1UserExists(cfg, user, opts) {
+  const users = await v1Show(cfg, 'SHOW USERS', opts);
+  return users.includes(user);
+}
+
+async function v1DatabaseExists(cfg, db, opts) {
+  const dbs = await v1Show(cfg, 'SHOW DATABASES', opts);
+  return dbs.includes(db);
+}
+
+async function v1GrantsFor(cfg, user, opts) {
+  try {
+    const rows = v1Rows(await v1Query(cfg, `SHOW GRANTS FOR ${ident(user)}`, opts));
+    return rows.map(([database, privilege]) => ({ database, privilege }));
+  } catch (err) {
+    return null;
+  }
+}
+
+// Create/repair the two users, the database and the seed measurement.
+// `phase` decides who runs the statements:
+//   bootstrap  → the temporary unauthenticated server (no credentials)
+//   persistent → the running authenticated server (admin credentials)
+async function provisionV1(cfg, creds, { phase, log }) {
+  const opts = phase === 'bootstrap'
+    ? { boot: true, database: cfg.database }
+    : { creds, admin: true };
+  const label = phase === 'bootstrap' ? ' (temporary unauthenticated server)' : '';
+  log(`creating/updating InfluxQL users + database${label}…`);
+
+  if (await v1UserExists(cfg, creds.ADMIN_USER, opts)) {
+    await v1Query(cfg, `SET PASSWORD FOR ${ident(creds.ADMIN_USER)} = ${sqlString(creds.ADMIN_PW)}`, opts);
+  } else {
+    await v1Query(
+      cfg,
+      `CREATE USER ${ident(creds.ADMIN_USER)} WITH PASSWORD ${sqlString(creds.ADMIN_PW)} WITH ALL PRIVILEGES`,
+      opts,
+    );
+  }
+
+  if (await v1UserExists(cfg, creds.APP_USER, opts)) {
+    await v1Query(cfg, `SET PASSWORD FOR ${ident(creds.APP_USER)} = ${sqlString(creds.APP_PW)}`, opts);
+  } else {
+    await v1Query(cfg, `CREATE USER ${ident(creds.APP_USER)} WITH PASSWORD ${sqlString(creds.APP_PW)}`, opts);
+  }
+
+  if (!(await v1DatabaseExists(cfg, cfg.database, opts))) {
+    await v1Query(cfg, `CREATE DATABASE ${ident(cfg.database)}`, opts);
+  }
+
+  // The app user gets ALL on its database only (the InfluxQL equivalent of
+  // MongoDB's readWrite on one database).
+  const grants = await v1GrantsFor(cfg, creds.APP_USER, opts);
+  const hasGrant = (grants || []).some(
+    (g) => g.database === cfg.database && /ALL/i.test(g.privilege || ''),
+  );
+  if (!hasGrant) {
+    await v1Query(cfg, `GRANT ALL ON ${ident(cfg.database)} TO ${ident(creds.APP_USER)}`, opts);
+  }
+
+  // Seed the measurement so a fresh instance is immediately usable (the
+  // equivalent of mongo-local-cli creating the initial collection).
+  if (cfg.measurement) {
+    const measurements = [];
+    try {
+      measurements.push(...(await v1Show(cfg, `SHOW MEASUREMENTS ON ${ident(cfg.database)}`, opts)));
+    } catch (err) {
+      // empty database returns no series
+    }
+    if (!measurements.includes(cfg.measurement)) {
+      await v1Query(
+        cfg,
+        `INSERT ${cfg.measurement},host=bootstrap,created_by=influx-local value=1`,
+        { ...opts, database: cfg.database },
+      );
+    }
+  }
+  log('users + database ready');
+  return creds;
+}
+
+// --- v2: onboarding, buckets, tokens ---------------------------------------
+
+const APP_TOKEN_DESCRIPTION = (cfg) => `influx-local app (rw ${cfg.database})`;
+const ADMIN_TOKEN_DESCRIPTION = 'influx-local admin (all-access)';
+
+async function v2TokenWorks(cfg, token) {
+  if (!token) return false;
+  const res = await httpProbe(`${httpBase(cfg)}/api/v2/buckets`, {
+    headers: { Authorization: `Token ${token}` },
+  });
+  return res.status === 200;
+}
+
+async function v2AppTokenWorks(cfg, token, creds) {
+  if (!token) return false;
+  const res = await runBin(cfg, cfg.cliBin, [
+    'query', '--host', httpBase(cfg), '--token', token, '--org', creds.ORG, '--raw',
+    `from(bucket: ${JSON.stringify(cfg.database)}) |> range(start: -1h) |> limit(n: 1)`,
+  ], {});
+  return res.code === 0;
+}
+
+async function v2BucketId(cfg, token, creds) {
+  const res = await runBin(cfg, cfg.cliBin, [
+    'bucket', 'list', '--host', httpBase(cfg), '--token', token,
+    '--org', creds.ORG, '--name', cfg.database, '--json',
+  ]);
+  if (res.code !== 0) return null;
+  try {
+    const buckets = JSON.parse(res.stdout.trim() || '[]');
+    return Array.isArray(buckets) && buckets.length ? buckets[0].id : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+async function v2AuthList(cfg, token) {
+  const res = await runBin(cfg, cfg.cliBin, [
+    'auth', 'list', '--host', httpBase(cfg), '--token', token, '--json',
+  ]);
+  if (res.code !== 0) return null;
+  try {
+    return JSON.parse(res.stdout.trim() || '[]');
+  } catch (err) {
+    return null;
+  }
+}
+
+async function v2CreateScopedToken(cfg, creds, { token, description, log }) {
+  const bucketId = await v2BucketId(cfg, token, creds);
+  if (!bucketId) throw new Error(`bucket "${cfg.database}" not found on ${httpBase(cfg)}`);
+  const res = await runBin(cfg, cfg.cliBin, [
+    'auth', 'create', '--host', httpBase(cfg), '--token', token, '--org', creds.ORG,
+    '--description', description, '--read-bucket', bucketId, '--write-bucket', bucketId, '--json',
+  ]);
+  if (res.code !== 0) throw new Error(errText('failed to create the app token', res));
+  const parsed = JSON.parse(res.stdout.trim() || '{}');
+  if (!parsed.token) throw new Error('the server did not return a token for the app authorization');
+  log(`created app token (read/write on bucket "${cfg.database}")`);
+  return { token: parsed.token, id: parsed.id, bucketId };
+}
+
+async function v2DeleteAuth(cfg, adminToken, id) {
+  if (!id) return;
+  const res = await runBin(cfg, cfg.cliBin, [
+    'auth', 'delete', '--host', httpBase(cfg), '--token', adminToken, '--id', id,
+  ]);
+  if (res.code !== 0) throw new Error(errText(`failed to delete authorization ${id}`, res));
+}
+
+// Onboarding + repair for 2.x. There is no unauthenticated window: `influx
+// setup` is the only way in, and it is refused once the instance is onboarded.
+async function provisionV2(cfg, creds, { phase, log }) {
+  const host = httpBase(cfg);
+  const setupState = await httpJson(`${host}/api/v2/setup`);
+  const allowed = setupState.json ? setupState.json.allowed : null;
+
+  if (allowed === true) {
+    log(`onboarding InfluxDB 2.x (user "${creds.ADMIN_USER}", org "${creds.ORG}", bucket "${cfg.database}")…`);
+    const res = await runBin(cfg, cfg.cliBin, [
+      'setup', '--host', host,
+      '--username', creds.ADMIN_USER,
+      '--password', creds.ADMIN_PW,
+      '--org', creds.ORG,
+      '--bucket', cfg.database,
+      '--token', creds.ADMIN_TOKEN,
+      '--retention', '0',
+      '--force',
+    ]);
+    if (res.code !== 0 && !/already set up/i.test(`${res.stderr}${res.stdout}`)) {
+      throw new Error(errText('influx setup failed', res));
+    }
+    // The CLI writes its own client config next to creds.env: keep it private.
+    await fs.chmod(cfg.cliConfigsPath, 0o600).catch(() => {});
+  } else if (allowed === false) {
+    log('instance is already onboarded — reconciling tokens/bucket (no re-setup)');
+  } else {
+    throw new Error(`cannot read the onboarding state from ${host}/api/v2/setup — is the server healthy?`);
+  }
+
+  if (!(await v2TokenWorks(cfg, creds.ADMIN_TOKEN))) {
+    throw new Error(
+      `the admin token in ${cfg.credsPath} was rejected by the server. ` +
+        `InfluxDB 2.x cannot re-issue an operator token for an onboarded instance: ` +
+        `restore creds.env or destroy the instance ("influx-local destroy ${cfg.name}") and set it up again.`,
+    );
+  }
+
+  // Repair: make sure the bucket exists.
+  if (!(await v2BucketId(cfg, creds.ADMIN_TOKEN, creds))) {
+    log(`creating bucket "${cfg.database}"…`);
+    const res = await runBin(cfg, cfg.cliBin, [
+      'bucket', 'create', '--host', host, '--token', creds.ADMIN_TOKEN,
+      '--org', creds.ORG, '--name', cfg.database, '--retention', '0',
+    ]);
+    if (res.code !== 0) throw new Error(errText(`failed to create bucket "${cfg.database}"`, res));
+  }
+
+  // Repair: make sure an app token exists and still works.
+  if (!(await v2AppTokenWorks(cfg, creds.APP_TOKEN, creds))) {
+    const list = await v2AuthList(cfg, creds.ADMIN_TOKEN);
+    const stale = (list || []).filter((a) => a.description === APP_TOKEN_DESCRIPTION(cfg));
+    for (const entry of stale) await v2DeleteAuth(cfg, creds.ADMIN_TOKEN, entry.id);
+    const created = await v2CreateScopedToken(cfg, creds, {
+      token: creds.ADMIN_TOKEN,
+      description: APP_TOKEN_DESCRIPTION(cfg),
+      log,
+    });
+    creds.APP_TOKEN = created.token;
+  } else {
+    log('app token is valid — nothing to repair');
+  }
+  return creds;
+}
+
+// --- v3: admin token + database --------------------------------------------
+
+async function v3TokenWorks(cfg, token) {
+  if (!token) return false;
+  const res = await runBin(cfg, cfg.serverBin, [
+    'show', 'databases', '--host', httpBase(cfg), '--token', token,
+  ]);
+  return res.code === 0;
+}
+
+function parseTokenOutput(stdout) {
+  const match = /apiv3_[A-Za-z0-9_=+/-]+/.exec(stdout);
+  if (match) return match[0];
+  const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  return lines.length ? lines[lines.length - 1] : null;
+}
+
+async function v3CreateAdminToken(cfg, { log }) {
+  const res = await runBin(cfg, cfg.serverBin, ['create', 'token', '--admin', '--host', httpBase(cfg)]);
+  const token = parseTokenOutput(res.stdout);
+  if (res.code !== 0 || !token) {
+    throw new Error(
+      errText(
+        'failed to create an admin token — InfluxDB 3 Core refuses to mint a second "_admin" token ' +
+          `for an already-initialised instance; remove ${cfg.dataDir} or restore creds.env`,
+        res,
+      ),
+    );
+  }
+  log('created a new admin token');
+  return token;
+}
+
+async function v3Databases(cfg, token) {
+  const res = await runBin(cfg, cfg.serverBin, [
+    'show', 'databases', '--host', httpBase(cfg), '--token', token, '--format', 'json',
+  ]);
+  if (res.code !== 0) return null;
+  const text = res.stdout.trim();
+  try {
+    const parsed = JSON.parse(text);
+    const rows = Array.isArray(parsed) ? parsed : parsed.data || parsed.databases || [];
+    if (rows.every((row) => typeof row === 'string')) return rows;
+    if (rows.every((row) => row && typeof row === 'object')) {
+      return rows
+        .map((row) => row['iox::database'] || row.database || row.name || Object.values(row)[0])
+        .filter(Boolean);
+    }
+    return null;
+  } catch (err) {
+    return null; // unknown shape: the caller falls back to a best-effort create
+  }
+}
+
+async function provisionV3(cfg, creds, { phase, log }) {
+  if (!(await v3TokenWorks(cfg, creds.ADMIN_TOKEN))) {
+    creds.ADMIN_TOKEN = await v3CreateAdminToken(cfg, { log });
+    // The server shows an admin token exactly once: persist it before doing
+    // anything else, or it is lost for good.
+    await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+    log(`saved the new admin token -> ${cfg.credsPath} (mode 0600)`);
+  } else {
+    log('admin token is valid');
+  }
+
+  const databases = await v3Databases(cfg, creds.ADMIN_TOKEN);
+  if (databases === null || !databases.includes(cfg.database)) {
+    log(`creating database "${cfg.database}"…`);
+    const res = await runBin(cfg, cfg.serverBin, [
+      'create', 'database', cfg.database, '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+    ]);
+    // When the database list could not be read we create unconditionally, so an
+    // "already exists" answer is not an error.
+    if (res.code !== 0 && !/already exists/i.test(`${res.stdout}${res.stderr}`)) {
+      throw new Error(errText(`failed to create database "${cfg.database}"`, res));
+    }
+  }
+
+  if (cfg.measurement) {
+    const tables = await v3Tables(cfg, creds.ADMIN_TOKEN).catch(() => null);
+    if (tables && !tables.includes(cfg.measurement)) {
+      const res = await runBin(cfg, cfg.serverBin, [
+        'write', '--database', cfg.database, '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+        `${cfg.measurement},host=bootstrap,created_by=influx-local value=1`,
+      ]);
+      if (res.code !== 0) throw new Error(errText(`failed to seed table "${cfg.measurement}"`, res));
+    }
+  }
+  log('admin token + database ready');
+  return creds;
+}
+
+async function v3Query(cfg, sql, { token, format = 'json' } = {}) {
+  const res = await runBin(cfg, cfg.serverBin, [
+    'query', '--database', cfg.database, '--host', httpBase(cfg), '--token', token, '--format', format, sql,
+  ]);
+  if (res.code !== 0) throw new Error(errText(`SQL statement failed: ${sql}`, res));
+  return res.stdout;
+}
+
+async function v3Tables(cfg, token) {
+  const out = await v3Query(cfg, 'SHOW TABLES', { token });
+  try {
+    const parsed = JSON.parse(out.trim() || '[]');
+    const rows = Array.isArray(parsed) ? parsed : parsed.data || [];
+    // 3 Core reports tables from the `iox` (user data) and `system` schemas.
+    return rows
+      .filter((row) => {
+        const schema = row.table_schema || row['table_schema'] || 'iox';
+        return schema !== 'system' && schema !== 'information_schema';
+      })
+      .map((row) => row.table_name || row.name)
+      .filter(Boolean);
+  } catch (err) {
+    return [];
+  }
+}
+
+// --- Flavor dispatch --------------------------------------------------------
+
+const PROVISIONERS = { v1: provisionV1, v2: provisionV2, v3: provisionV3 };
+
+function provision(cfg, creds, { phase, log }) {
+  return PROVISIONERS[cfg.flavor](cfg, creds, { phase, log });
+}
+
+// Do the managed credentials still work against the running server?
+async function verifyAdmin(cfg, creds) {
+  if (!creds) return false;
+  try {
+    if (cfg.flavor === 'v1') {
+      const res = await httpProbe(`${httpBase(cfg)}/query?db=admin&q=SHOW+DATABASES`, {
+        headers: { Authorization: basicAuth(creds.ADMIN_USER, creds.ADMIN_PW) },
+      });
+      return res.status === 200;
+    }
+    if (cfg.flavor === 'v2') return v2TokenWorks(cfg, creds.ADMIN_TOKEN);
+    return v3TokenWorks(cfg, creds.ADMIN_TOKEN);
+  } catch (err) {
+    return false;
+  }
+}
+
+// --- Public operations ------------------------------------------------------
+
+async function startInstance(name, { log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  await ensureDirs(cfg);
+  const pid = await readPidFile(cfg.pidPath);
+  if (pid && pidAlive(pid)) {
+    if (await instancePortBound(cfg)) {
+      return { alreadyRunning: true, pid, config: cfg };
+    }
+    log(`pid ${pid} exists but port ${cfg.port} is not bound — cleaning up stale daemon…`);
+    await stopPid(pid, { force: true, log, name: cfg.serverBin });
+    await fs.rm(cfg.pidPath, { force: true }).catch(() => {});
+  }
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) {
+    throw new Error(
+      `no credentials for "${name}" yet — run "influx-local setup ${name}" once to create users and start the server`,
+    );
+  }
+  if (await checkPort(cfg.port, probeHost(cfg))) {
+    throw new Error(`port ${cfg.port} is occupied by a process this tool does not manage — stop it first, or change the port`);
+  }
+  try {
+    const startedPid = await spawnDaemon(cfg, { log });
+    if (!(await waitReady(cfg, { timeoutMs: 30000 }))) {
+      const tail = await logTail(cfg.logPath, 15);
+      throw new Error(`${cfg.serverBin} did not become ready on ${httpBase(cfg)}${tail ? `\n  ${path.basename(cfg.logPath)} tail:\n${tail}` : ''}`);
+    }
+    if (!(await verifyAdmin(cfg, creds))) {
+      throw new Error(
+        `credentials in ${cfg.credsPath} were rejected on ${httpBase(cfg)} — the data directory is not provisioned (or is out of sync)`,
+      );
+    }
+    return { alreadyRunning: false, pid: startedPid, config: cfg };
+  } catch (err) {
+    // Heal the common trap: a data dir that has no managed credentials yet.
+    if (/were rejected|not provisioned|no matching/i.test(err.message)) {
+      log('authentication failed — running automatic setup/repair (keeps data)…');
+      const healed = await setupInstance(name, { log });
+      return { alreadyRunning: false, pid: healed.pid, config: healed.config || cfg, healed: true };
+    }
+    throw err;
+  }
+}
+
+// Full provisioning + start.
+//   already running & credentials OK → repair online (no restart)
+//   otherwise                        → 1.x: temporary unauthenticated server
+//                                      2.x/3.x: start, then provision over the API
+async function setupInstance(name, { log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  await ensureDirs(cfg);
+  await installTools(cfg, log);
+
+  const pid = await readPidFile(cfg.pidPath);
+  const running = pid != null && pidAlive(pid);
+  let creds = await resolveCreds(cfg, log);
+
+  if (running) {
+    if (await verifyAdmin(cfg, creds)) {
+      log('instance is running and credentials are valid — repairing online (no restart)');
+      creds = await provision(cfg, creds, { phase: 'online', log });
+      await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+      return { online: true, pid, config: cfg, credsPath: cfg.credsPath };
+    }
+    log('credentials were rejected — falling back to offline repair');
+    await stopDaemon(cfg, { log });
+  }
+
+  if (await checkPort(cfg.port, probeHost(cfg))) {
+    throw new Error(
+      `port ${cfg.port} is occupied by a process this tool does not manage — stop it first, or change the port`,
+    );
+  }
+
+  // InfluxDB 1.x users can only be created while authentication is off, so the
+  // instance is provisioned through a short-lived unauthenticated server bound
+  // to 127.0.0.1 and then restarted with auth enabled.
+  if (cfg.flavor === 'v1') {
+    log(`starting temporary ${cfg.serverBin} (no auth) on 127.0.0.1:${cfg.port}…`);
+    const bootPid = await spawnDaemon(cfg, { boot: true, log });
+    try {
+      if (!(await waitReady(cfg, { boot: true, timeoutMs: 30000 }))) {
+        throw new Error(`temporary ${cfg.serverBin} did not become ready`);
+      }
+      creds = await provision(cfg, creds, { phase: 'bootstrap', log });
+    } finally {
+      if (bootPid && pidAlive(bootPid)) {
+        log(`stopping temporary ${cfg.serverBin} (pid ${bootPid})…`);
+        await stopPid(bootPid, { log, name: cfg.serverBin });
+      }
+      await fs.rm(cfg.bootPidPath, { force: true }).catch(() => {});
+      if (!(await waitPortFree(cfg))) {
+        throw new Error(`port ${cfg.port} is still occupied after stopping the temporary server`);
+      }
+    }
+  }
+
+  const finalPid = await spawnDaemon(cfg, { log });
+  if (!(await waitReady(cfg, { timeoutMs: 30000 }))) {
+    const tail = await logTail(cfg.logPath, 15);
+    throw new Error(`${cfg.serverBin} did not become ready on ${httpBase(cfg)}${tail ? `\n  ${path.basename(cfg.logPath)} tail:\n${tail}` : ''}`);
+  }
+
+  if (cfg.flavor !== 'v1') {
+    creds = await provision(cfg, creds, { phase: 'persistent', log });
+  }
+  await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+
+  if (!(await verifyAdmin(cfg, creds))) {
+    const tail = await logTail(cfg.logPath, 15);
+    throw new Error(
+      `${cfg.serverBin} did not accept the admin credentials on ${httpBase(cfg)}${tail ? `\n  ${path.basename(cfg.logPath)} tail:\n${tail}` : ''}`,
+    );
+  }
+  return { online: false, pid: finalPid, config: cfg, credsPath: cfg.credsPath };
+}
+
+async function stopInstance(name, { force = false, log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  const pid = await readPidFile(cfg.pidPath);
+  if (!pid || !pidAlive(pid)) {
+    return { alreadyStopped: true, config: cfg };
+  }
+  await stopPid(pid, { force, log, name: cfg.serverBin });
+  await fs.rm(cfg.pidPath, { force: true }).catch(() => {});
+  return { alreadyStopped: false, forced: force, config: cfg };
+}
+
+async function restartInstance(name, { force = false, log = noopLog } = {}) {
+  await stopInstance(name, { force, log });
+  return startInstance(name, { log });
+}
+
+// First free port at or after `start` (used for clones / create defaults).
+async function nextFreePort(start, host = '127.0.0.1', maxAttempts = 50) {
+  for (let port = start; port < start + maxAttempts; port++) {
+    if (!(await checkPort(port, host))) return port;
+  }
+  return start;
+}
+
+// Rename an instance by moving its directory. The server must be stopped first
+// (pid/log/data paths live inside the directory).
+async function renameInstance(name, newName, { log = noopLog } = {}) {
+  if (!(await configMod.configExists(name))) throw new Error(`instance "${name}" not found`);
+  configMod.assertValidInstanceName(newName);
+  if (await configMod.configExists(newName)) throw new Error(`instance "${newName}" already exists`);
+  const cfg = await loadConfig(name);
+  const pid = await readPidFile(cfg.pidPath);
+  if (pid && pidAlive(pid)) {
+    throw new Error(`stop "${name}" first, then re-run the rename`);
+  }
+  await fs.rename(cfg.instanceDir, configMod.getInstanceDir(newName));
+  log(`renamed "${name}" -> "${newName}"`);
+  return newName;
+}
+
+// Clone: copies config + credentials into a new instance directory (no data).
+// The clone is stopped; run setup to provision it.
+async function cloneInstance(name, newName, { port, log = noopLog } = {}) {
+  if (!(await configMod.configExists(name))) throw new Error(`instance "${name}" not found`);
+  configMod.assertValidInstanceName(newName);
+  if (await configMod.configExists(newName)) throw new Error(`instance "${newName}" already exists`);
+  const stored = JSON.parse(await fs.readFile(configMod.getConfigPath(name), 'utf8'));
+  const srcCfg = await loadConfig(name);
+  const flavor = flavorOf(stored.version || srcCfg.version);
+  const finalPort = port != null ? port : await nextFreePort((stored.port || srcCfg.port) + 1, srcCfg.host);
+  await configMod.saveConfig(newName, { ...stored, port: finalPort });
+  await saveMiseToml(newName, stored.version || srcCfg.version);
+  const creds = await readCreds(name, flavor.id);
+  if (creds) await writeCreds(newName, flavor.id, creds, { ...srcCfg, database: stored.database || name });
+  log(`cloned "${name}" -> "${newName}" (port ${finalPort})`);
+  return { name: newName, port: finalPort, config: await loadConfig(newName) };
+}
+
+// --- Users ------------------------------------------------------------------
+
+const V1_PRIVILEGES = ['read', 'write', 'all'];
+const USER_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+function assertUserName(username) {
+  if (typeof username !== 'string' || !USER_NAME.test(username)) {
+    throw new Error(`invalid username "${username}" — 1-64 chars, letters/digits/dot/dash/underscore, start alnum`);
+  }
+}
+
+function requireCapability(cfg, capability, what) {
+  if (!cfg.capabilities[capability]) {
+    throw new Error(`${cfg.flavorLabel} does not support ${what}`);
+  }
+}
+
+async function requireRunning(cfg) {
+  const pid = await readPidFile(cfg.pidPath);
+  if (!pid || !pidAlive(pid)) {
+    throw new Error(`${cfg.serverBin} is not running — start it with "influx-local start ${cfg.name}", then re-run`);
+  }
+}
+
+async function listUsers(name) {
+  const cfg = await loadConfig(name);
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  const builtins = [];
+  if (cfg.flavor === 'v1') {
+    builtins.push(
+      { user: creds ? creds.ADMIN_USER : cfg.adminUser, db: 'admin', roles: ['all privileges'], builtin: true },
+      { user: creds ? creds.APP_USER : cfg.appUser, db: cfg.database, roles: ['all'], builtin: true },
+    );
+  } else if (cfg.flavor === 'v2') {
+    builtins.push({ user: creds ? creds.ADMIN_USER : cfg.adminUser, db: cfg.org, roles: ['operator'], builtin: true });
+  } else {
+    builtins.push({ user: '_admin (token)', db: cfg.org, roles: ['admin token'], builtin: true });
+  }
+
+  const pid = await readPidFile(cfg.pidPath);
+  if (!pid || !pidAlive(pid) || !creds) return { running: false, users: builtins };
+
+  try {
+    if (cfg.flavor === 'v1') {
+      const users = await v1Show(cfg, 'SHOW USERS', { creds, admin: true });
+      const merged = [];
+      for (const user of users) {
+        const grants = await v1GrantsFor(cfg, user, { creds, admin: true });
+        const adminUser = user === creds.ADMIN_USER;
+        const roleText = adminUser
+          ? 'all privileges'
+          : (grants || []).map((g) => `${g.privilege} on ${g.database}`).join(', ') || '—';
+        merged.push({
+          user,
+          db: adminUser ? 'admin' : (grants || []).map((g) => g.database).join(','),
+          roles: [roleText],
+          builtin: user === creds.ADMIN_USER || user === creds.APP_USER,
+        });
+      }
+      return { running: true, users: merged };
+    }
+
+    if (cfg.flavor === 'v2') {
+      const res = await runBin(cfg, cfg.cliBin, [
+        'user', 'list', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN, '--json',
+      ]);
+      if (res.code !== 0) {
+        return { running: true, users: builtins, error: errText('failed to list users on the server', res) };
+      }
+      const users = JSON.parse(res.stdout.trim() || '[]');
+      const merged = [...builtins];
+      for (const u of users) {
+        if (!merged.some((b) => b.user === u.name)) {
+          merged.push({
+            user: u.name,
+            db: cfg.org,
+            roles: [u.name === creds.ADMIN_USER ? 'operator' : 'member'],
+            builtin: u.name === creds.ADMIN_USER,
+          });
+        }
+      }
+      return { running: true, users: merged };
+    }
+
+    // 3 Core: tokens, not users.
+    const res = await runBin(cfg, cfg.serverBin, [
+      'show', 'tokens', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN, '--format', 'json',
+    ]);
+    let tokens = [];
+    if (res.code === 0) {
+      try {
+        const parsed = JSON.parse(res.stdout.trim() || '[]');
+        const rows = Array.isArray(parsed) ? parsed : parsed.data || [];
+        tokens = rows.map((row) => row.name).filter(Boolean);
+      } catch (err) {
+        tokens = [];
+      }
+    }
+    return {
+      running: true,
+      users: [
+        ...builtins,
+        ...tokens.filter((t) => t !== '_admin').map((t) => ({ user: t, db: '—', roles: ['token'], builtin: false })),
+      ],
+    };
+  } catch (err) {
+    return { running: true, users: builtins, error: err.message };
+  }
+}
+
+async function addUser(name, { username, db = 'database', password, privileges, log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  requireCapability(cfg, 'users', 'creating users');
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+  await requireRunning(cfg);
+  assertUserName(username);
+  if (typeof password !== 'string' || password.length < 6) throw new Error('password must be at least 6 characters');
+
+  if (cfg.flavor === 'v1') {
+    // `db` arrives as the literal 'database' when --db is omitted.
+    const requested = db === 'database' ? cfg.database : db;
+    if (requested !== 'admin' && requested !== cfg.database) {
+      throw new Error(`target must be "admin" or "${cfg.database}" (got "${db}")`);
+    }
+    const scope = requested === 'admin' ? 'admin' : cfg.database;
+    const list = (privileges && privileges.length ? privileges : ['all']).map((p) => p.toLowerCase());
+    for (const p of list) {
+      if (!V1_PRIVILEGES.includes(p)) {
+        throw new Error(`invalid privilege "${p}" — valid values: ${V1_PRIVILEGES.join(', ')}`);
+      }
+    }
+    const opts = { creds, admin: true };
+    if (await v1UserExists(cfg, username, opts)) {
+      throw new Error(`user "${username}" already exists`);
+    }
+    const withAdmin = scope === 'admin' && list.includes('all');
+    await v1Query(
+      cfg,
+      `CREATE USER ${ident(username)} WITH PASSWORD ${sqlString(password)}${withAdmin ? ' WITH ALL PRIVILEGES' : ''}`,
+      opts,
+    );
+    if (!withAdmin) {
+      for (const p of list) {
+        await v1Query(cfg, `GRANT ${p.toUpperCase()} ON ${ident(scope)} TO ${ident(username)}`, opts);
+      }
+    }
+    log(`created user "${username}" (${withAdmin ? 'all privileges' : `${list.join(', ')} on ${scope}`})`);
+    return { user: username, db: scope, privileges: withAdmin ? ['all privileges'] : list };
+  }
+
+  // 2.x
+  const res = await runBin(cfg, cfg.cliBin, [
+    'user', 'create', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+    '--name', username, '--password', password, '--org', creds.ORG, '--json',
+  ]);
+  if (res.code !== 0) throw new Error(errText(`failed to create user "${username}"`, res));
+  log(`created user "${username}" on org "${creds.ORG}" (InfluxDB 2.x scopes access with tokens, not user roles)`);
+  return { user: username, db: creds.ORG, privileges: ['member'] };
+}
+
+async function setAnyPassword(name, { username, password, log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  requireCapability(cfg, 'userPasswords', 'setting user passwords');
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+  await requireRunning(cfg);
+  assertUserName(username);
+  if (typeof password !== 'string' || password.length < 6) throw new Error('password must be at least 6 characters');
+
+  if (cfg.flavor === 'v1') {
+    const opts = { creds, admin: true };
+    if (!(await v1UserExists(cfg, username, opts))) throw new Error(`user "${username}" not found`);
+    await v1Query(cfg, `SET PASSWORD FOR ${ident(username)} = ${sqlString(password)}`, opts);
+  } else {
+    const res = await runBin(cfg, cfg.cliBin, [
+      'user', 'password', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+      '--name', username, '--password', password,
+    ]);
+    if (res.code !== 0) throw new Error(errText(`failed to update the password for "${username}"`, res));
+  }
+  log(`updated password for "${username}"`);
+  return { user: username };
+}
+
+async function removeUser(name, { username, log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  requireCapability(cfg, 'users', 'deleting users');
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+  await requireRunning(cfg);
+  assertUserName(username);
+  if (
+    (cfg.flavor === 'v1' && (username === creds.ADMIN_USER || username === creds.APP_USER)) ||
+    (cfg.flavor === 'v2' && username === creds.ADMIN_USER)
+  ) {
+    throw new Error(`refusing to delete the built-in user "${username}" (it is stored in creds.env)`);
+  }
+
+  if (cfg.flavor === 'v1') {
+    const opts = { creds, admin: true };
+    if (!(await v1UserExists(cfg, username, opts))) throw new Error(`user "${username}" not found`);
+    await v1Query(cfg, `DROP USER ${ident(username)}`, opts);
+  } else {
+    const res = await runBin(cfg, cfg.cliBin, [
+      'user', 'delete', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN, '--name', username,
+    ]);
+    if (res.code !== 0) throw new Error(errText(`failed to delete user "${username}"`, res));
+  }
+  log(`deleted user "${username}"`);
+  return { user: username };
+}
+
+// --- Status / logs / doctor -------------------------------------------------
+
+function urisFor(cfg, creds) {
+  if (!creds) return null;
+  const host = cfg.host === '0.0.0.0' || cfg.host === '::' ? '127.0.0.1' : cfg.host;
+  const publicHost = cfg.publicHost;
+  const uris = { endpoint: `http://${host}:${cfg.port}` };
+  const build = (h) => {
+    if (cfg.flavor === 'v1') {
+      return {
+        appUri: `influxdb://${encodeURIComponent(creds.APP_USER)}:${encodeURIComponent(creds.APP_PW)}@${h}:${cfg.port}/${cfg.database}`,
+        adminUri: `influxdb://${encodeURIComponent(creds.ADMIN_USER)}:${encodeURIComponent(creds.ADMIN_PW)}@${h}:${cfg.port}`,
+      };
+    }
+    if (cfg.flavor === 'v2') {
+      const out = {
+        adminUri: `influxdb2://${encodeURIComponent(creds.ADMIN_TOKEN)}@${h}:${cfg.port}?org=${encodeURIComponent(creds.ORG)}`,
+      };
+      // The app token only exists once setup has provisioned it.
+      if (creds.APP_TOKEN) {
+        out.appUri = `influxdb2://${encodeURIComponent(creds.APP_TOKEN)}@${h}:${cfg.port}?org=${encodeURIComponent(creds.ORG)}&bucket=${encodeURIComponent(cfg.database)}`;
+      }
+      return out;
+    }
+    return {
+      appUri: `influxdb3://${encodeURIComponent(creds.ADMIN_TOKEN)}@${h}:${cfg.port}/${cfg.database}`,
+    };
+  };
+  Object.assign(uris, build(host));
+  if (publicHost) {
+    const pub = build(publicHost);
+    for (const [key, value] of Object.entries(pub)) {
+      uris[`public${key[0].toUpperCase()}${key.slice(1)}`] = value;
+    }
+  }
+  return uris;
+}
+
+async function serverVersion(cfg) {
+  if (cfg.flavor === 'v1') {
+    try {
+      const res = await fetch(`${httpBase(cfg)}/ping`, { signal: AbortSignal.timeout(2000) });
+      return res.headers.get('x-influxdb-version') || null;
+    } catch (err) {
+      return null;
+    }
+  }
+  const res = await httpJson(`${httpBase(cfg)}/health`);
+  if (res.json && res.json.version) return res.json.version;
+  return cfg.version;
+}
+
+async function measurements(cfg, creds) {
+  try {
+    if (cfg.flavor === 'v1') {
+      return await v1Show(cfg, 'SHOW MEASUREMENTS', { creds, database: cfg.database });
+    }
+    if (cfg.flavor === 'v3') return await v3Tables(cfg, creds.ADMIN_TOKEN);
+
+    const res = await runBin(cfg, cfg.cliBin, [
+      'query', '--host', httpBase(cfg), '--token', creds.APP_TOKEN, '--org', creds.ORG, '--raw',
+      `import "influxdata/influxdb/schema"\nschema.measurements(bucket: ${JSON.stringify(cfg.database)})`,
+    ]);
+    if (res.code !== 0) return [];
+    return res.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#') && !/^(,)?result/.test(line))
+      .map((line) => line.split(',').pop())
+      .filter((value) => value && value !== '_value');
+  } catch (err) {
+    return null;
+  }
+}
+
+async function getStatus(name, { detail = true } = {}) {
+  const cfg = await loadConfig(name);
+  const pid = await readPidFile(cfg.pidPath);
+  const pidLive = pid != null && pidAlive(pid);
+  const bound = await instancePortBound(cfg);
+  const running = pidLive && bound;
+  const state = running ? 'running' : bound ? 'port-conflict' : pidLive ? 'stale-pid' : 'stopped';
+  const creds = await readCreds(cfg.name, cfg.flavor);
+
+  const status = {
+    name: cfg.name,
+    state,
+    running,
+    pid: running ? pid : null,
+    stalePid: !running && pidLive ? pid : null,
+    flavor: cfg.flavor,
+    flavorLabel: cfg.flavorLabel,
+    version: cfg.version,
+    installedVersion: null,
+    host: cfg.host,
+    port: cfg.port,
+    endpoint: `http://${cfg.host === '0.0.0.0' ? '127.0.0.1' : cfg.host}:${cfg.port}`,
+    database: cfg.database,
+    measurement: cfg.capabilities.measurement ? cfg.measurement : null,
+    org: cfg.flavor === 'v2' ? cfg.org : null,
+    adminUser: cfg.flavor === 'v3' ? null : (creds ? creds.ADMIN_USER : cfg.adminUser),
+    appUser: cfg.flavor === 'v1' ? (creds ? creds.APP_USER : cfg.appUser) : null,
+    credsFile: creds ? cfg.credsPath : null,
+    dataDir: cfg.dataDir,
+    logPath: cfg.logPath,
+    runningVersion: null,
+    measurements: null,
+    uris: null,
+    config: cfg,
+  };
+
+  if (running && creds) {
+    status.uris = urisFor(cfg, creds);
+    if (detail) {
+      status.runningVersion = await serverVersion(cfg);
+      status.measurements = await measurements(cfg, creds);
+    }
+  }
+  return status;
+}
+
+// Rotate the managed secrets on the running server.
+//   v1: SET PASSWORD for the admin/app users
+//   v2: a fresh all-access admin token (+ operator password) and/or app token
+//   v3: delete + re-create the admin token through a short unauthenticated window
+async function rotateInstance(name, { users = 'all', log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  if (!['all', 'admin', 'app'].includes(users)) {
+    throw new Error(`rotate target must be one of: all, admin, app (got "${users}")`);
+  }
+  const pid = await readPidFile(cfg.pidPath);
+  if (!pid || !pidAlive(pid)) {
+    throw new Error(`${cfg.serverBin} is not running — start it with "influx-local start ${name}", then re-run`);
+  }
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+
+  const doAdmin = users === 'all' || users === 'admin';
+  const doApp = users === 'all' || users === 'app';
+
+  if (cfg.flavor === 'v1') {
+    if (doAdmin) {
+      const next = randomPassword();
+      await v1Query(cfg, `SET PASSWORD FOR ${ident(creds.ADMIN_USER)} = ${sqlString(next)}`, { creds, admin: true });
+      creds.ADMIN_PW = next;
+    }
+    if (doApp) {
+      const next = randomPassword();
+      await v1Query(cfg, `SET PASSWORD FOR ${ident(creds.APP_USER)} = ${sqlString(next)}`, { creds, admin: true });
+      creds.APP_PW = next;
+    }
+    await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+    log(`${[doAdmin && 'admin', doApp && 'app'].filter(Boolean).join(' + ')} password(s) rotated`);
+    await verifyRotated(cfg, creds);
+    return { changed: { admin: doAdmin, app: doApp } };
+  }
+
+  if (cfg.flavor === 'v2') {
+    if (doAdmin) {
+      const nextPassword = randomPassword();
+      const res = await runBin(cfg, cfg.cliBin, [
+        'user', 'password', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+        '--name', creds.ADMIN_USER, '--password', nextPassword,
+      ]);
+      if (res.code !== 0) throw new Error(errText('failed to rotate the operator password', res));
+
+      const created = await runBin(cfg, cfg.cliBin, [
+        'auth', 'create', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN, '--org', creds.ORG,
+        '--description', ADMIN_TOKEN_DESCRIPTION, '--all-access', '--json',
+      ]);
+      if (created.code !== 0) throw new Error(errText('failed to create a replacement admin token', created));
+      const parsed = JSON.parse(created.stdout.trim() || '{}');
+      if (!parsed.token) throw new Error('the server did not return a replacement admin token');
+
+      const staleIds = ((await v2AuthList(cfg, creds.ADMIN_TOKEN)) || [])
+        .filter((a) => a.token === creds.ADMIN_TOKEN)
+        .map((a) => a.id);
+      creds.ADMIN_PW = nextPassword;
+      creds.ADMIN_TOKEN = parsed.token;
+      for (const id of staleIds) await v2DeleteAuth(cfg, creds.ADMIN_TOKEN, id);
+    }
+    if (doApp) {
+      const staleIds = ((await v2AuthList(cfg, creds.ADMIN_TOKEN)) || [])
+        .filter((a) => a.description === APP_TOKEN_DESCRIPTION(cfg))
+        .map((a) => a.id);
+      const created = await v2CreateScopedToken(cfg, creds, {
+        token: creds.ADMIN_TOKEN,
+        description: APP_TOKEN_DESCRIPTION(cfg),
+        log,
+      });
+      creds.APP_TOKEN = created.token;
+      for (const id of staleIds) {
+        if (id !== created.id) await v2DeleteAuth(cfg, creds.ADMIN_TOKEN, id);
+      }
+    }
+    await writeCreds(cfg.name, cfg.flavor, creds, cfg);
+    log(`${[doAdmin && 'admin', doApp && 'app'].filter(Boolean).join(' + ')} secret(s) rotated`);
+    await verifyRotated(cfg, creds);
+    return { changed: { admin: doAdmin, app: doApp } };
+  }
+
+  // 3 Core: the only credential is the admin token. InfluxDB refuses to mint a
+  // second "_admin" token, so the old one is removed through a short
+  // unauthenticated window and a fresh one is created.
+  throw new Error(
+    'InfluxDB 3 Core cannot rotate its admin token in place (the server refuses to create a second "_admin" token).\n' +
+      `  Rotate by recreating the instance: "influx-local destroy ${name} && influx-local setup ${name}"`,
+  );
+}
+
+async function verifyRotated(cfg, creds) {
+  if (!(await verifyAdmin(cfg, creds))) {
+    throw new Error('the new credentials were not accepted — creds.env and the server are out of sync; re-run setup to repair');
+  }
+  if (cfg.flavor === 'v2' && creds.APP_TOKEN) {
+    if (!(await v2AppTokenWorks(cfg, creds.APP_TOKEN, creds))) {
+      throw new Error('the new app token was not accepted — creds.env and the server are out of sync; re-run setup to repair');
+    }
+  }
+}
+
+// Set an explicit password (v1/v2). v3 has no password at all.
+async function setPassword(name, { user = 'admin', password, log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  if (cfg.flavor === 'v3') {
+    throw new Error(`${cfg.flavorLabel} authenticates with tokens only — there is no password to set`);
+  }
+  if (!['admin', 'app'].includes(user)) throw new Error(`password target must be admin or app (got "${user}")`);
+  if (cfg.flavor === 'v1' && user === 'app') {
+    // handled below (app user exists in 1.x)
+  } else if (cfg.flavor === 'v2' && user === 'app') {
+    throw new Error('InfluxDB 2.x scopes access with tokens, not an app user — use "influx-local rotate --app" to replace the app token');
+  }
+  if (typeof password !== 'string' || password.length < 6) {
+    throw new Error('password must be a string of at least 6 characters');
+  }
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+
+  const pid = await readPidFile(cfg.pidPath);
+  const running = pid != null && pidAlive(pid);
+  const field = user === 'admin' ? 'ADMIN_PW' : 'APP_PW';
+  const next = { ...creds, [field]: password };
+
+  if (!running) {
+    await writeCreds(cfg.name, cfg.flavor, next, cfg);
+    log(`updated creds.env for "${user}" — server is stopped; run setup to apply it on the server`);
+    return { user, applied: false };
+  }
+
+  if (cfg.flavor === 'v1') {
+    const username = user === 'admin' ? creds.ADMIN_USER : creds.APP_USER;
+    await v1Query(cfg, `SET PASSWORD FOR ${ident(username)} = ${sqlString(password)}`, { creds, admin: true });
+  } else {
+    const res = await runBin(cfg, cfg.cliBin, [
+      'user', 'password', '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+      '--name', creds.ADMIN_USER, '--password', password,
+    ]);
+    if (res.code !== 0) throw new Error(errText('failed to change the operator password', res));
+  }
+  await writeCreds(cfg.name, cfg.flavor, next, cfg);
+  const refreshed = await readCreds(cfg.name, cfg.flavor);
+  await verifyRotated(cfg, refreshed);
+  log(`${user} password updated on the running server`);
+  return { user, applied: true };
+}
+
+async function destroyInstance(name, { log = noopLog } = {}) {
+  const cfg = await loadConfig(name);
+  const pid = await readPidFile(cfg.pidPath);
+  if (pid && pidAlive(pid)) {
+    await stopPid(pid, { log, name: cfg.serverBin });
+    await fs.rm(cfg.pidPath, { force: true }).catch(() => {});
+  }
+  const bootPid = await readPidFile(cfg.bootPidPath);
+  if (bootPid && pidAlive(bootPid)) {
+    await stopPid(bootPid, { force: true, log, name: cfg.serverBin });
+  }
+  if (await checkPort(cfg.port, probeHost(cfg))) {
+    throw new Error(`port ${cfg.port} is occupied by a process this tool does not manage — stop it first, then re-run`);
+  }
+  await configMod.deleteInstanceDir(name);
+}
+
+async function readLogTail(name, maxLines = 200) {
+  const cfg = await loadConfig(name);
+  const logPath = cfg.logPath;
+  let stat;
+  try {
+    stat = await fs.stat(logPath);
+    if (!stat.isFile()) throw new Error('not a file');
+  } catch (err) {
+    return { logPath, text: '', missing: true };
+  }
+  const chunkSize = Math.min(256 * 1024, stat.size);
+  const handle = await fs.open(logPath, 'r');
+  let text = '';
+  try {
+    const buf = Buffer.alloc(chunkSize);
+    const { bytesRead } = await handle.read(buf, 0, chunkSize, Math.max(0, stat.size - chunkSize));
+    text = buf.slice(0, bytesRead).toString('utf8');
+  } finally {
+    await handle.close();
+  }
+  const lines = text.split(/\r?\n/);
+  return { logPath, text: lines.slice(-maxLines).join('\n'), missing: false };
+}
+
+async function doctorInstance(name) {
+  const cfg = await loadConfig(name);
+  const checks = [];
+
+  const mise = await spawnOut(miseBin(), ['--version']).catch((err) => ({ code: 1, stderr: err.message }));
+  checks.push({
+    ok: mise.code === 0,
+    label: `mise is available (${miseBin()})`,
+    detail: mise.code === 0 ? String(mise.stdout || '').trim() : 'install mise first: https://mise.jdx.dev',
+  });
+
+  try {
+    const artifacts = artifactsFor(cfg.version);
+    checks.push({
+      ok: true,
+      label: `flavor / version`,
+      detail: `${cfg.flavorLabel} ${cfg.version} — auth: ${cfg.auth}, artifacts: ${artifacts.map((a) => a.tool).join(', ')}`,
+    });
+  } catch (err) {
+    checks.push({ ok: false, label: 'flavor / version', detail: err.message });
+  }
+
+  checks.push({ ok: true, label: 'instance configuration', detail: cfg.dataDir });
+
+  let installed = null;
+  try {
+    installed = await resolveBins(cfg, { require: false });
+  } catch (err) {
+    installed = {};
+  }
+  const serverBin = installed[cfg.serverBin];
+  checks.push({
+    ok: !!serverBin,
+    label: `InfluxDB ${cfg.version} installed`,
+    detail: serverBin || `missing — run "influx-local install ${name}"`,
+  });
+
+  const pid = await readPidFile(cfg.pidPath);
+  checks.push({
+    ok: !pid || pidAlive(pid),
+    label: 'pid file state',
+    detail: pid ? `pid ${pid} ${pidAlive(pid) ? 'alive' : 'STALE'}` : 'no pid file (stopped)',
+  });
+
+  const portInUse = await checkPort(cfg.port, probeHost(cfg));
+  checks.push({
+    ok: !portInUse || (pid != null && pidAlive(pid)),
+    label: `port ${cfg.port}`,
+    detail: portInUse ? 'in use' : 'free',
+  });
+
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  checks.push({
+    ok: !!creds,
+    label: 'credentials file',
+    detail: creds
+      ? `found (${Object.keys(creds).filter((k) => !k.endsWith('_PW')).join(', ')})`
+      : 'missing — run "influx-local setup" to create',
+  });
+
+  try {
+    await fs.access(cfg.dataDir, fs.constants.W_OK);
+    checks.push({ ok: true, label: 'data directory writable', detail: cfg.dataDir });
+  } catch (err) {
+    checks.push({ ok: false, label: 'data directory writable', detail: `${cfg.dataDir} (${err.code || err.message})` });
+  }
+
+  return checks;
+}
+
+// Interactive shell: 1.x has a REPL, 2.x/3.x do not.
+async function shellInstance(name, { admin = false, args = [] } = {}) {
+  const cfg = await loadConfig(name);
+  requireCapability(cfg, 'shell', 'an interactive shell');
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+  const bins = await resolveBins(cfg);
+  const argv = [...v1BaseArgs(cfg, { creds, admin, format: null, database: cfg.database }), ...args];
+  const res = await new Promise((resolve, reject) => {
+    const child = spawn(bins[cfg.cliBin], argv, { stdio: 'inherit', env: baseEnv() });
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code));
+  });
+  return res;
+}
+
+// One-shot query in the instance's native language:
+//   v1 → InfluxQL (influx -execute)   v2 → Flux (influx query)   v3 → SQL
+async function queryInstance(name, statement, { admin = false, format = 'pretty' } = {}) {
+  const cfg = await loadConfig(name);
+  const creds = await readCreds(cfg.name, cfg.flavor);
+  if (!creds) throw new Error(`no credentials for "${name}" — run "influx-local setup ${name}" first`);
+  await requireRunning(cfg);
+
+  if (cfg.flavor === 'v1') {
+    const args = [...v1BaseArgs(cfg, { creds, admin, database: cfg.database }), '-execute', statement];
+    const res = await runBin(cfg, cfg.cliBin, args);
+    return { code: res.code, stdout: res.stdout, stderr: res.stderr };
+  }
+  if (cfg.flavor === 'v2') {
+    const res = await runBin(cfg, cfg.cliBin, [
+      'query', '--host', httpBase(cfg), '--token', admin ? creds.ADMIN_TOKEN : creds.APP_TOKEN,
+      '--org', creds.ORG, '--raw', statement,
+    ]);
+    return { code: res.code, stdout: res.stdout, stderr: res.stderr };
+  }
+  const res = await runBin(cfg, cfg.serverBin, [
+    'query', '--database', cfg.database, '--host', httpBase(cfg), '--token', creds.ADMIN_TOKEN,
+    '--format', format, statement,
+  ]);
+  return { code: res.code, stdout: res.stdout, stderr: res.stderr };
+}
+
+// True when the instance's data dir already holds a server's files (used to
+// refuse switching an instance between incompatible InfluxDB lines).
+async function instanceHasData(cfg) {
+  try {
+    const entries = await fs.readdir(cfg.dataDir);
+    return entries.length > 0;
+  } catch (err) {
+    return false;
+  }
+}
+
+async function listStatuses() {
+  const names = await configMod.listInstances();
+  const out = [];
+  for (const name of names) {
+    const status = await getStatus(name, { detail: false });
+    out.push({
+      name,
+      state: status.state,
+      running: status.running,
+      pid: status.pid,
+      port: status.port,
+      host: status.host,
+      database: status.database,
+      version: status.version,
+      flavor: status.flavor,
+      flavorLabel: status.flavorLabel,
+    });
+  }
+  return out;
+}
+
+module.exports = {
+  installTools,
+  checkPort,
+  nextFreePort,
+  startInstance,
+  setupInstance,
+  stopInstance,
+  restartInstance,
+  getStatus,
+  listStatuses,
+  rotateInstance,
+  setPassword,
+  destroyInstance,
+  renameInstance,
+  cloneInstance,
+  listUsers,
+  addUser,
+  setAnyPassword,
+  removeUser,
+  readLogTail,
+  doctorInstance,
+  shellInstance,
+  queryInstance,
+  resolveBins,
+  verifyAdmin,
+  instanceHasData,
+  httpBase,
+  probeHost,
+  baseEnv,
+};