influx-local-cli 0.1.0

package/src/versions.js

@@ -0,0 +1,270 @@
+'use strict';
+
+// InfluxDB ships three incompatible product lines from one GitHub repository.
+// An instance pins exactly one version; the "flavor" (v1/v2/v3) is derived from
+// that version's major number and decides which binaries, daemon flags, auth
+// model, storage layout and credentials this tool manages.
+//
+// Tarballs come from dl.influxdata.com: InfluxData publishes no GitHub release
+// assets for these tags, so mise's github/ubi backends cannot install influxd.
+// Instead every instance carries its own .mise.toml declaring a custom `http:`
+// tool with the exact URL for its pinned version (see `miseTomlFor`).
+
+const RELEASES = 'https://dl.influxdata.com/influxdb/releases';
+
+// mise's placeholders are {{ version }}-style; we substitute the platform tag
+// ourselves so the generated file stays readable.
+const PLATFORMS = {
+  'linux-x64': 'linux_amd64',
+  'linux-arm64': 'linux_arm64',
+  'darwin-x64': 'darwin_amd64',
+  'darwin-arm64': 'darwin_arm64',
+};
+
+function platformTag(platform = process.platform, arch = process.arch) {
+  const tag = PLATFORMS[`${platform}-${arch}`];
+  if (!tag) {
+    throw new Error(
+      `unsupported platform ${platform}-${arch}: InfluxDB tarballs are published for linux/darwin on x64/arm64 only`,
+    );
+  }
+  return tag;
+}
+
+// Version catalogs: every entry below was verified to exist on
+// dl.influxdata.com (HTTP 206/200). Tags exist in the git repo that have no
+// artifact (e.g. 1.12.4, 2.7.12) — hence a curated list instead of "all tags".
+const FLAVORS = {
+  v1: {
+    id: 'v1',
+    label: 'InfluxDB 1.x (InfluxQL)',
+    auth: 'basic',
+    defaultPort: 8086,
+    serverBin: 'influxd',
+    cliBin: 'influx',
+    // v1 is the closest match to the classic "admin user + app user with a
+    // database-scoped grant + a shell" model.
+    capabilities: { users: true, userPasswords: true, rotatePassword: true, shell: true, measurement: true },
+    versions: ['1.7.11', '1.8.0', '1.8.4', '1.8.6', '1.8.9', '1.8.10'],
+    defaultVersion: '1.8.10',
+    artifacts: (version) => [
+      {
+        tool: 'influxdb-1x',
+        exe: ['influxd', 'influx'],
+        url: `${RELEASES}/influxdb-${version}_${platformTag()}.tar.gz`,
+        stripComponents: 1,
+        binPath: 'usr/bin',
+      },
+    ],
+  },
+  v2: {
+    id: 'v2',
+    label: 'InfluxDB 2.x (Flux)',
+    auth: 'token',
+    defaultPort: 8086,
+    serverBin: 'influxd',
+    cliBin: 'influx',
+    capabilities: { users: true, userPasswords: true, rotatePassword: true, shell: false, measurement: false },
+    versions: ['2.7.3', '2.7.5', '2.7.7', '2.7.9', '2.7.10', '2.7.11', '2.8.0', '2.9.0', '2.9.1'],
+    defaultVersion: '2.7.11',
+    // The server tarball ships no CLI, so the client is a second artifact.
+    clientVersion: '2.7.5',
+    artifacts: (version) => [
+      {
+        tool: 'influxdb-2x',
+        exe: ['influxd'],
+        url: `${RELEASES}/influxdb2-${version}_${platformTag()}.tar.gz`,
+        stripComponents: 1,
+        binPath: 'usr/bin',
+      },
+      {
+        tool: 'influxdb-2x-cli',
+        exe: ['influx'],
+        artifactVersion: clientVersionFor(version),
+        url: `${RELEASES}/influxdb2-client-${clientVersionFor(version)}-${platformTag().replace('_', '-')}.tar.gz`,
+        stripComponents: 1,
+        binPath: '.',
+      },
+    ],
+  },
+  v3: {
+    id: 'v3',
+    label: 'InfluxDB 3 Core (SQL)',
+    auth: 'token',
+    defaultPort: 8181,
+    serverBin: 'influxdb3',
+    cliBin: 'influxdb3',
+    // 3 Core has a single binary that is both server (`serve`) and client
+    // (`query`, `create`, `show`). Only an admin token exists — no users and no
+    // per-database token scoping — so user/token-scoping commands are refused.
+    capabilities: { users: false, userPasswords: false, rotatePassword: true, shell: false, measurement: true },
+    versions: [
+      '3.0.0', '3.0.3', '3.3.0', '3.4.0', '3.9.0',
+      '3.10.0', '3.10.6', '3.11.2', '3.11.3', '3.11.4',
+    ],
+    defaultVersion: '3.11.4',
+    artifacts: (version) => [
+      {
+        tool: 'influxdb-3x',
+        exe: ['influxdb3'],
+        url: `${RELEASES}/influxdb3-core-${version}_${platformTag()}.tar.gz`,
+        stripComponents: 1,
+        binPath: '.',
+      },
+    ],
+  },
+};
+
+const FLAVOR_ORDER = ['v1', 'v2', 'v3'];
+const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+
+// The client CLI tracks the server line, not its exact patch: the client
+// catalog is much smaller than the server catalog.
+function clientVersionFor(version) {
+  const major = String(version).split('.')[0];
+  if (major !== '2') return FLAVORS.v2.clientVersion;
+  const minor = parseInt(String(version).split('.')[1], 10);
+  if (minor <= 6) return '2.6.1';
+  if (minor === 7 && parseInt(String(version).split('.')[2], 10) <= 3) return '2.7.3';
+  return '2.7.5';
+}
+
+function flavorIdForVersion(version) {
+  const m = VERSION_PATTERN.exec(String(version || '').trim());
+  if (!m) {
+    throw new Error(
+      `invalid InfluxDB version "${version}" — expected a full version such as 1.8.10, 2.7.11 or 3.11.4 ` +
+        '(run "influx-local versions" for the list of published versions)',
+    );
+  }
+  const id = `v${m[1]}`;
+  if (!FLAVORS[id]) {
+    throw new Error(
+      `unsupported InfluxDB major version "${m[1]}" — this tool manages the 1.x, 2.x and 3.x lines (got "${version}")`,
+    );
+  }
+  return id;
+}
+
+function flavor(id) {
+  const f = FLAVORS[id];
+  if (!f) throw new Error(`unknown InfluxDB flavor "${id}"`);
+  return f;
+}
+
+function flavorOf(version) {
+  return flavor(flavorIdForVersion(version));
+}
+
+function isKnownVersion(version) {
+  let id;
+  try {
+    id = flavorIdForVersion(version);
+  } catch (err) {
+    return false;
+  }
+  return FLAVORS[id].versions.includes(String(version));
+}
+
+function artifactsFor(version) {
+  return flavorOf(version).artifacts(String(version));
+}
+
+// Accept a full version (1.8.10), a line shorthand (1.x/2.x/3.x) or a flavor id.
+function resolveVersionInput(input) {
+  const raw = String(input == null ? '' : input).trim();
+  if (!raw) throw new Error('a version is required (run "influx-local versions" for the catalog)');
+  const line = /^(\d+)\.x$/i.exec(raw);
+  if (line) {
+    const f = FLAVORS[`v${line[1]}`];
+    if (!f) throw new Error(`unknown InfluxDB line "${raw}" — use 1.x, 2.x or 3.x`);
+    return f.defaultVersion;
+  }
+  flavorOf(raw); // validates the major and the X.Y.Z shape
+  return raw;
+}
+
+// Every version this tool knows how to install, grouped by line.
+function versionCatalog() {
+  const out = [];
+  for (const id of FLAVOR_ORDER) {
+    const f = FLAVORS[id];
+    for (const version of f.versions) {
+      out.push({
+        version,
+        flavor: id,
+        label: f.label,
+        auth: f.auth,
+        defaultPort: f.defaultPort,
+        default: version === f.defaultVersion,
+      });
+    }
+  }
+  return out;
+}
+
+// The .mise.toml an instance carries: pins the version and teaches mise how to
+// fetch it (there is no registry entry to fall back on).
+function miseTomlFor(version) {
+  const f = flavorOf(version);
+  const lines = [
+    `# Generated by influx-local — do not edit by hand.`,
+    `# Instance toolchain: ${f.label}, version ${version}.`,
+    `# InfluxData publishes server tarballs on dl.influxdata.com (GitHub release`,
+    `# assets are empty), so mise installs them through the generic http backend.`,
+    '',
+    '[tools]',
+  ];
+  for (const a of artifactsFor(version)) {
+    lines.push(
+      `"http:${a.tool}" = { version = "${version === version && a.tool.includes('cli') ? f.clientVersion : version}", ` +
+        `url = "${a.url}", strip_components = "${a.stripComponents}", bin_path = "${a.binPath}" }`,
+    );
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Credentials an instance keeps in creds.env, per auth model.
+//   v1: two InfluxQL users (admin = ALL PRIVILEGES, app = ALL on the database)
+//   v2: an operator user + all-access token, plus a bucket-scoped app token
+//       (APP_TOKEN is minted by the server during onboarding, so it is not part
+//        of the required set — `create` writes the file before setup runs)
+//   v3: an admin token only (3 Core has no per-database scoping)
+const CRED_FIELDS = {
+  v1: ['ADMIN_USER', 'ADMIN_PW', 'APP_USER', 'APP_PW'],
+  v2: ['ADMIN_USER', 'ADMIN_PW', 'ADMIN_TOKEN', 'ORG', 'BUCKET'],
+  v3: ['ADMIN_TOKEN'],
+};
+
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+function assertIdentifier(value, what) {
+  if (typeof value !== 'string' || !NAME_PATTERN.test(value)) {
+    throw new Error(
+      `invalid ${what} "${value}" — 1-64 chars: letters, digits, dots, dashes or underscores; must start with a letter or digit`,
+    );
+  }
+  return value;
+}
+
+module.exports = {
+  RELEASES,
+  PLATFORMS,
+  platformTag,
+  FLAVORS,
+  FLAVOR_ORDER,
+  VERSION_PATTERN,
+  NAME_PATTERN,
+  flavor,
+  flavorOf,
+  flavorIdForVersion,
+  isKnownVersion,
+  artifactsFor,
+  resolveVersionInput,
+  versionCatalog,
+  miseTomlFor,
+  clientVersionFor,
+  CRED_FIELDS,
+  assertIdentifier,
+};

package/src/web.js

@@ -0,0 +1,387 @@
+'use strict';
+
+const path = require('path');
+const crypto = require('crypto');
+const express = require('express');
+const manager = require('./manager');
+const configMod = require('./config');
+const { versionCatalog, resolveVersionInput, flavorOf, FLAVORS } = require('./versions');
+const {
+  loadConfig,
+  saveConfig,
+  listInstances,
+  assertValidInstanceName,
+  configExists,
+  readCreds,
+  SETTABLE_KEYS,
+} = configMod;
+
+function maskSecrets(uri) {
+  let out = String(uri).replace(/\/\/([^:@/]+):([^@/]+)@/, '//$1:•••••••@');
+  out = out.replace(/\/\/([^:@/]+)@/, '//•••••••@');
+  return out;
+}
+
+// Single-slot operation queue: only one op runs at a time (the same server must
+// not be poked concurrently). Polled by the dashboard.
+let currentOp = null;
+let opSeq = 0;
+
+async function runOp(kind, instance, fn) {
+  const id = `op-${++opSeq}`;
+  currentOp = { id, instance, kind, lines: [], running: true, error: null, startedAt: new Date().toISOString() };
+  const emit = (line) => {
+    currentOp.lines.push(String(line));
+    if (currentOp.lines.length > 2000) currentOp.lines.splice(0, currentOp.lines.length - 2000);
+  };
+  try {
+    const result = await fn(emit);
+    currentOp.result = result;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    currentOp.error = msg;
+    // Failed ops stay visible in /api/state (rendered by the UI).
+  } finally {
+    currentOp.running = false;
+    currentOp.finishedAt = new Date().toISOString();
+  }
+  return currentOp;
+}
+
+// Validate + apply a config patch (shared by the bulk and single-key routes).
+async function applyConfigPatch(name, patch) {
+  const cfg = await loadConfig(name);
+  for (const [key, rawValue] of Object.entries(patch)) {
+    const value = rawValue == null ? '' : String(rawValue);
+    if (key === 'port') {
+      const port = parseInt(value, 10);
+      if (Number.isNaN(port) || port <= 0 || port > 65535) throw new Error('port must be 1-65535');
+      cfg.port = port;
+    } else if (key === 'version') {
+      const next = resolveVersionInput(value);
+      const nextFlavor = flavorOf(next);
+      if (nextFlavor.id !== cfg.flavor && (await manager.instanceHasData(cfg))) {
+        throw new Error(
+          `refusing to switch "${name}" from ${cfg.flavorLabel} to ${nextFlavor.label}: InfluxDB stores data in a line-specific format. Create a new instance instead.`,
+        );
+      }
+      cfg.version = next;
+    } else {
+      if (value === '' && key !== 'publicHost') throw new Error(`value for "${key}" must not be empty`);
+      cfg[key] = value;
+    }
+  }
+  await saveConfig(name, cfg);
+  if ('version' in patch) await configMod.saveMiseToml(name, cfg.version);
+  const updated = {};
+  for (const key of SETTABLE_KEYS) updated[key] = cfg[key];
+  return updated;
+}
+
+function startWeb({ host = '127.0.0.1', port = 8788, token = '' } = {}) {
+  return new Promise((resolve, reject) => {
+    const app = express();
+    app.use(express.json());
+
+    // Optional bearer-token protection for the API.
+    app.use('/api', (req, res, next) => {
+      if (!token) return next();
+      const provided = req.get('x-influx-local-token') || '';
+      const a = Buffer.from(String(provided));
+      const b = Buffer.from(String(token));
+      if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+        return res.status(401).json({ error: 'invalid or missing token (set it with --token)' });
+      }
+      next();
+    });
+
+    const sendErr = (res, status, message) => res.status(status).json({ error: message });
+
+    // --- API -----------------------------------------------------------------
+    app.get('/api/state', async (req, res) => {
+      try {
+        const statuses = await manager.listStatuses();
+        const op = currentOp
+          ? {
+              id: currentOp.id,
+              instance: currentOp.instance,
+              kind: currentOp.kind,
+              running: currentOp.running,
+              error: currentOp.error,
+              startedAt: currentOp.startedAt,
+              finishedAt: currentOp.finishedAt || null,
+              lines: currentOp.lines,
+              result: currentOp.result || null,
+            }
+          : null;
+        res.json({
+          instances: statuses,
+          op,
+          tokenRequired: !!token,
+          baseDir: configMod.BASE_DIR,
+        });
+      } catch (err) {
+        sendErr(res, 500, err.message);
+      }
+    });
+
+    // Catalog for the "new instance" version picker.
+    app.get('/api/versions', (req, res) => {
+      res.json({
+        versions: versionCatalog(),
+        flavors: Object.values(FLAVORS).map((f) => ({
+          id: f.id,
+          label: f.label,
+          auth: f.auth,
+          defaultPort: f.defaultPort,
+          defaultVersion: f.defaultVersion,
+          capabilities: f.capabilities,
+        })),
+      });
+    });
+
+    app.get('/api/instances/:name', async (req, res) => {
+      try {
+        assertValidInstanceName(req.params.name);
+        if (!(await configExists(req.params.name))) return sendErr(res, 404, 'instance not found');
+        const status = await manager.getStatus(req.params.name);
+        const creds = await readCreds(req.params.name, status.flavor);
+        const cfg = await loadConfig(req.params.name);
+        const { config, uris, ...plain } = status;
+        if (uris) {
+          plain.uris = {};
+          for (const key of Object.keys(uris)) plain.uris[key] = maskSecrets(uris[key]);
+          plain.uris.masked = true;
+        }
+        plain.credsPresent = !!creds;
+        plain.credsFields = creds ? Object.keys(creds).filter((k) => !k.endsWith('_PW')) : [];
+        const settable = {};
+        for (const key of SETTABLE_KEYS) settable[key] = cfg[key];
+        plain.config = settable;
+        plain.capabilities = cfg.capabilities;
+        plain.dataDir = cfg.dataDir;
+        plain.miseToml = cfg.miseTomlPath;
+        res.json(plain);
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.put('/api/instances/:name/config', async (req, res) => {
+      try {
+        assertValidInstanceName(req.params.name);
+        if (!(await configExists(req.params.name))) return sendErr(res, 404, 'instance not found');
+        const body = req.body || {};
+
+        // Bulk update: body = { key: value, ... } for any settable keys.
+        if (!('key' in body)) {
+          const keys = Object.keys(body).filter((k) => SETTABLE_KEYS.includes(k));
+          if (keys.length === 0) {
+            return sendErr(res, 400, `no valid keys supplied; valid keys: ${SETTABLE_KEYS.join(', ')}`);
+          }
+          const patch = {};
+          for (const key of keys) patch[key] = body[key];
+          const updated = await applyConfigPatch(req.params.name, patch);
+          return res.json({ ok: true, updated, restartNote: true });
+        }
+
+        // Single-key update (fine-grained): body = { key, value }.
+        const { key, value } = body;
+        if (!SETTABLE_KEYS.includes(key)) {
+          return sendErr(res, 400, `invalid key "${key}"; valid: ${SETTABLE_KEYS.join(', ')}`);
+        }
+        const updated = await applyConfigPatch(req.params.name, { [key]: value });
+        res.json({ ok: true, key, value: updated[key], restartNote: true });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.post('/api/instances/:name/rename', async (req, res) => {
+      try {
+        if (currentOp && currentOp.running) return sendErr(res, 409, 'another operation is running');
+        const src = assertValidInstanceName(req.params.name);
+        const newName = assertValidInstanceName((req.body || {}).newName);
+        if (!(await configExists(src))) return sendErr(res, 404, 'instance not found');
+        const result = await manager.renameInstance(src, newName);
+        res.json({ ok: true, name: result });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.post('/api/instances/:name/clone', async (req, res) => {
+      try {
+        if (currentOp && currentOp.running) return sendErr(res, 409, 'another operation is running');
+        const src = assertValidInstanceName(req.params.name);
+        const body = req.body || {};
+        const newName = assertValidInstanceName(body.name);
+        if (!(await configExists(src))) return sendErr(res, 404, 'instance not found');
+        let port;
+        if (body.port !== undefined && body.port !== '') {
+          port = parseInt(body.port, 10);
+          if (Number.isNaN(port) || port <= 0 || port > 65535) return sendErr(res, 400, 'port must be 1-65535');
+        }
+        const result = await manager.cloneInstance(src, newName, { port });
+        res.status(201).json({ ok: true, name: result.name, port: result.port });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.get('/api/instances/:name/users', async (req, res) => {
+      try {
+        const name = assertValidInstanceName(req.params.name);
+        if (!(await configExists(name))) return sendErr(res, 404, 'instance not found');
+        res.json(await manager.listUsers(name));
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.get('/api/instances/:name/secrets', async (req, res) => {
+      try {
+        assertValidInstanceName(req.params.name);
+        if (!(await configExists(req.params.name))) return sendErr(res, 404, 'instance not found');
+        const cfg = await loadConfig(req.params.name);
+        const creds = await readCreds(req.params.name, cfg.flavor);
+        if (!creds) return sendErr(res, 404, 'no credentials yet — run setup');
+        const status = await manager.getStatus(req.params.name, { detail: false });
+        res.json({ flavor: cfg.flavor, creds, uris: status.uris || null });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.get('/api/instances/:name/logs', async (req, res) => {
+      try {
+        assertValidInstanceName(req.params.name);
+        const lines = Math.min(Math.max(parseInt(req.query.lines, 10) || 200, 1), 5000);
+        res.json(await manager.readLogTail(req.params.name, lines));
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.post('/api/instances', async (req, res) => {
+      try {
+        const body = req.body || {};
+        const name = assertValidInstanceName(body.name);
+        if (await configExists(name)) return sendErr(res, 409, `instance "${name}" already exists`);
+
+        const version = resolveVersionInput(body.version === undefined || body.version === '' ? configMod.DEFAULT_VERSION : body.version);
+        const flavor = flavorOf(version);
+        const patch = { version, database: body.database || name };
+        if (body.port !== undefined && body.port !== '') {
+          const port = parseInt(body.port, 10);
+          if (Number.isNaN(port) || port <= 0 || port > 65535) return sendErr(res, 400, 'port must be 1-65535');
+          patch.port = port;
+        }
+        if (body.host) patch.host = body.host;
+        if (body.publicHost) patch.publicHost = body.publicHost;
+        if (body.measurement && flavor.capabilities.measurement) patch.measurement = body.measurement;
+        if (flavor.id === 'v2' && body.org) patch.org = body.org;
+        if (flavor.id !== 'v3') patch.adminUser = body.adminUser || 'admin';
+        if (flavor.id === 'v1') patch.appUser = body.appUser || 'app';
+
+        const cfg = await loadConfig(name);
+        Object.assign(cfg, patch);
+        await saveConfig(name, cfg);
+        await configMod.saveMiseToml(name, version);
+
+        const saved = await loadConfig(name);
+        if (saved.flavor === 'v1') {
+          await configMod.writeCreds(name, 'v1', {
+            ADMIN_USER: saved.adminUser,
+            ADMIN_PW: body.adminPassword ? String(body.adminPassword) : configMod.randomPassword(),
+            APP_USER: saved.appUser,
+            APP_PW: body.appPassword ? String(body.appPassword) : configMod.randomPassword(),
+          }, saved);
+        } else if (saved.flavor === 'v2') {
+          await configMod.writeCreds(name, 'v2', {
+            ADMIN_USER: saved.adminUser,
+            ADMIN_PW: body.adminPassword ? String(body.adminPassword) : configMod.randomPassword(),
+            ADMIN_TOKEN: configMod.randomToken(),
+            APP_TOKEN: '',
+            ORG: saved.org,
+            BUCKET: saved.database,
+          }, saved);
+        }
+        res.status(201).json({ ok: true, name, version, flavor: saved.flavor });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.delete('/api/instances/:name', async (req, res) => {
+      try {
+        const name = assertValidInstanceName(req.params.name);
+        if (currentOp && currentOp.running) return sendErr(res, 409, 'another operation is running');
+        if (!(await configExists(name))) return sendErr(res, 404, 'instance not found');
+        if ((req.query.confirm || '') !== name) {
+          return sendErr(res, 400, `confirm parameter must equal the instance name ("${name}")`);
+        }
+        const op = await runOp('destroy', name, async (log) => {
+          await manager.destroyInstance(name, { log });
+          return { destroyed: true };
+        });
+        res.status(202).json({ opId: op.id });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    const ACTIONS = {
+      setup: (name, o, log) => manager.setupInstance(name, { log }),
+      start: (name, o, log) => manager.startInstance(name, { log }),
+      stop: (name, o, log) => manager.stopInstance(name, { force: !!o.force, log }),
+      restart: (name, o, log) => manager.restartInstance(name, { force: !!o.force, log }),
+      rotate: (name, o, log) => manager.rotateInstance(name, { users: o.users || 'all', log }),
+      install: (name, o, log) => loadConfig(name).then((cfg) => manager.installTools(cfg, log)),
+      'set-password': (name, o, log) =>
+        manager.setPassword(name, { user: o.user || 'admin', password: o.password, log }),
+      'user-add': (name, o, log) =>
+        manager.addUser(name, { username: o.username, db: o.db, password: o.password, privileges: o.privileges, log }),
+      'user-password': (name, o, log) =>
+        manager.setAnyPassword(name, { username: o.username, password: o.password, log }),
+      'user-rm': (name, o, log) => manager.removeUser(name, { username: o.username, log }),
+    };
+
+    app.post('/api/actions', async (req, res) => {
+      try {
+        const body = req.body || {};
+        if (!body.instance || typeof body.instance !== 'string') {
+          return sendErr(res, 400, 'missing "instance" in the request — reload the page and retry');
+        }
+        const name = assertValidInstanceName(body.instance);
+        const action = ACTIONS[body.action];
+        if (!action) return sendErr(res, 400, `unknown action "${body.action}"; valid: ${Object.keys(ACTIONS).join(', ')}`);
+        if (currentOp && currentOp.running) return sendErr(res, 409, 'another operation is running');
+        if (!(await configExists(name))) return sendErr(res, 404, 'instance not found');
+        const opts = body.opts || {};
+        const op = await runOp(body.action, name, (log) => action(name, opts, log));
+        if (op.error) return res.status(200).json({ opId: op.id, error: op.error });
+        res.status(202).json({ opId: op.id });
+      } catch (err) {
+        sendErr(res, 400, err.message);
+      }
+    });
+
+    app.get('/api/health', (req, res) => res.json({ ok: true }));
+
+    // --- Static dashboard -----------------------------------------------------
+    app.use((req, res, next) => {
+      if (!req.path.startsWith('/api')) res.set('Cache-Control', 'no-store');
+      next();
+    });
+    app.use(express.static(path.join(__dirname, '..', 'web'), { index: 'index.html' }));
+
+    const server = app.listen(port, host, () => {
+      const actual = server.address().port;
+      resolve({ server, url: `http://${host}:${actual}`, port: actual, host });
+    });
+    server.on('error', (err) => reject(err));
+  });
+}
+
+module.exports = { startWeb };