@serfab/cadre-host 0.7.1

package/src/server/routes/nat.ts

@@ -0,0 +1,63 @@
+/**
+ * NAT/DDNS HTTP routes — thin adapters around `NatHandlers`
+ * (`createNatHandlers(service)`). Side-effects (settings change, reachability
+ * re-test, DDNS reconfiguration) emit a `connectivity-changed` bus event.
+ *
+ * Mount path: `/nat/*` — matches the existing CLI (cadre-host nat ...).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { NatHandlers, NatSettingsFile, NatStatusSnapshot } from '../../nat/types.js';
+import type { EventBus } from '../events/bus.js';
+
+export interface NatRoutesOptions {
+  handlers: NatHandlers;
+  events: EventBus;
+}
+
+export function registerNatRoutes(app: FastifyInstance, opts: NatRoutesOptions): void {
+  const { handlers, events } = opts;
+
+  app.get('/nat/status', async () => handlers.getStatus());
+
+  app.post('/nat/test', async () => {
+    const snap = await handlers.testReachability();
+    publishConnectivity(events, snap);
+    return snap;
+  });
+
+  app.get('/nat/providers', async () => handlers.listDdnsProviders());
+
+  app.put('/nat/ddns', async (request) => {
+    const body = (request.body ?? {}) as {
+      providerId?: string;
+      hostname?: string;
+      config?: Record<string, string>;
+      externallyManaged?: boolean;
+    };
+    const snap = await handlers.putDdns({
+      providerId: body.providerId ?? '',
+      hostname: body.hostname ?? '',
+      config: body.config ?? {},
+      externallyManaged: body.externallyManaged ?? false,
+    });
+    publishConnectivity(events, snap);
+    return snap;
+  });
+
+  app.put('/nat/settings', async (request) => {
+    const body = (request.body ?? {}) as Partial<Omit<NatSettingsFile, 'version'>>;
+    const snap = await handlers.putSettings(body);
+    publishConnectivity(events, snap);
+    return snap;
+  });
+}
+
+export function publishConnectivity(events: EventBus, snap: NatStatusSnapshot): void {
+  events.publish({
+    type: 'connectivity-changed',
+    portMode: snap.portMode,
+    directReachability: snap.directReachability,
+  });
+}

package/src/server/routes/nodes.ts

@@ -0,0 +1,147 @@
+/**
+ * /api/nodes — list managed cadre nodes, look up details, and control
+ * lifecycle.
+ *
+ * Bus events for lifecycle transitions are emitted by the orchestrator's
+ * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
+ * handlers don't re-publish.
+ *
+ * v1 limits: cadre-host doesn't yet auto-spawn nodes (the trust-circle →
+ * node mapping ticket is separate). Until it lands, `listNodes()` is
+ * usually empty and start/restart are stubs. Stop on a running node works.
+ */
+
+import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
+
+import type { FastifyInstance } from 'fastify';
+
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import { defaultLogPath } from '../../orchestrator/log-rotator.js';
+
+const DEFAULT_LOG_LINES = 200;
+const MAX_LOG_LINES = 2000;
+
+export interface NodesRoutesOptions {
+  orchestrator: HostProcessOrchestrator;
+}
+
+export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptions): void {
+  const { orchestrator } = opts;
+
+  app.get('/api/nodes', async () => {
+    return { ok: true, data: { nodes: orchestrator.listNodes() } };
+  });
+
+  app.get<{ Params: { id: string } }>('/api/nodes/:id', async (request, reply) => {
+    const node = orchestrator.getNode(request.params.id);
+    if (!node) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+      });
+    }
+    let stats = null;
+    try {
+      stats = await orchestrator.getStats(node.dockerId);
+    } catch {
+      // Stats unavailable (dead process etc.) — surface null.
+    }
+    return { ok: true, data: { node, stats } };
+  });
+
+  app.get<{ Params: { id: string }; Querystring: { lines?: string } }>(
+    '/api/nodes/:id/logs',
+    async (request, reply) => {
+      const node = orchestrator.getNode(request.params.id);
+      if (!node) {
+        return reply.code(404).send({
+          ok: false,
+          error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+        });
+      }
+      const requested = Number(request.query.lines ?? DEFAULT_LOG_LINES);
+      const tail = Number.isFinite(requested)
+        ? Math.max(1, Math.min(MAX_LOG_LINES, Math.floor(requested)))
+        : DEFAULT_LOG_LINES;
+      const lines = tailLogFile(defaultLogPath(node.workdir), tail);
+      return { ok: true, data: { lines } };
+    },
+  );
+
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/stop', async (request, reply) => {
+    const dockerId = orchestrator.resolveDockerId(request.params.id);
+    if (!dockerId) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+      });
+    }
+    await orchestrator.stopContainer(dockerId);
+    // The orchestrator emits its own onStateChange — createLocalUiServer
+    // forwards that to the bus. Don't double-publish here.
+    return { ok: true };
+  });
+
+  // start / restart: the orchestrator's createContainer requires a full
+  // OrchestratorCreateRequest (partyId, bootstrapNodes, profile, ...).
+  // cadre-host doesn't yet own a "spawn this node from saved config" path
+  // — that lives in the trust-circle-driven node spawner planned for a
+  // follow-up ticket. Until then these endpoints stub out cleanly so the
+  // SPA gets a predictable error rather than a route-not-found 404.
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
+    return reply.code(501).send({
+      ok: false,
+      error: {
+        code: 'not_implemented',
+        message:
+          `start ${request.params.id}: cadre-host v1 has no auto-spawn path. ` +
+          `Restart the cadre-host service to bring up persisted nodes.`,
+      },
+    });
+  });
+
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
+    return reply.code(501).send({
+      ok: false,
+      error: {
+        code: 'not_implemented',
+        message:
+          `restart ${request.params.id}: cadre-host v1 has no auto-spawn path. ` +
+          `Restart the cadre-host service to bring up persisted nodes.`,
+      },
+    });
+  });
+}
+
+/**
+ * Read the last `n` lines from a log file by walking the tail in chunks.
+ * Returns [] for a missing file.
+ */
+export function tailLogFile(path: string, n: number): string[] {
+  if (!existsSync(path)) return [];
+  const fd = openSync(path, 'r');
+  try {
+    const size = statSync(path).size;
+    const chunkSize = 8192;
+    let pos = size;
+    const buffers: Buffer[] = [];
+    let newlineCount = 0;
+    while (pos > 0 && newlineCount <= n) {
+      const readLen = Math.min(chunkSize, pos);
+      pos -= readLen;
+      const buf = Buffer.alloc(readLen);
+      readSync(fd, buf, 0, readLen, pos);
+      buffers.unshift(buf);
+      for (let i = 0; i < buf.length; i++) {
+        if (buf[i] === 0x0a) newlineCount++;
+      }
+    }
+    const joined = Buffer.concat(buffers).toString('utf8');
+    const lines = joined.split('\n');
+    const trimmed = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+    return trimmed.slice(-n);
+  } finally {
+    closeSync(fd);
+  }
+}
+

package/src/server/routes/settings.ts

@@ -0,0 +1,115 @@
+/**
+ * /api/settings — host-level settings UI surface.
+ *
+ * The persisted shape is `host.config.json` (managed by the installer).
+ * This route is a thin passthrough plus a write-whitelist:
+ *
+ *   - uiPort        rejected (restart required; only edit at install time)
+ *   - libp2pPort    rejected (restart required)
+ *   - upnpEnabled   accepted → also propagated to NatService.putSettings
+ *   - updates.autoApply  accepted → propagated to UpdateService.putSettings
+ *   - updates.manifestUrl accepted → propagated to UpdateService.putSettings
+ *   - anything else 400 invalid_setting
+ *
+ * GET returns the full `HostConfigFile` (the SPA wants the full shape so it
+ * can render a read-only view of the rejected keys).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { NatService } from '../../nat/index.js';
+import type { UpdateService } from '../../update/index.js';
+import type { HostSettingsStore } from '../settings-store.js';
+
+const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version']);
+
+const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
+const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
+
+export interface SettingsRoutesOptions {
+  settingsStore: HostSettingsStore;
+  nat: NatService;
+  update?: UpdateService;
+}
+
+export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoutesOptions): void {
+  const { settingsStore, nat, update } = opts;
+
+  app.get('/api/settings', async () => {
+    return { ok: true, data: settingsStore.read() };
+  });
+
+  app.put('/api/settings', async (request, reply) => {
+    const body = (request.body ?? {}) as Record<string, unknown>;
+    const validation = validatePatch(body);
+    if (validation.error) {
+      return reply.code(400).send({
+        ok: false,
+        error: { code: 'invalid_setting', message: validation.error },
+      });
+    }
+
+    const current = settingsStore.read();
+    const patch: { upnpEnabled?: boolean; updates?: typeof current.updates } = {};
+
+    if ('upnpEnabled' in body) {
+      patch.upnpEnabled = body.upnpEnabled as boolean;
+      // Propagate UPnP toggle into the running NatService so the change
+      // takes effect immediately. NatService persists into nat.json — that's
+      // independent of host.config.json's `upnpEnabled` (which the installer
+      // uses on first run to seed nat.json). Update both for consistency.
+      await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+    }
+    if ('updates' in body) {
+      const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };
+      const nextUpdates = { ...current.updates };
+      if ('autoApply' in updates) nextUpdates.autoApply = updates.autoApply as boolean;
+      if ('manifestUrl' in updates) nextUpdates.manifestUrl = updates.manifestUrl as string;
+      patch.updates = nextUpdates;
+      if (update) {
+        const propagate: { autoApply?: boolean; manifestUrl?: string } = {};
+        if ('autoApply' in updates) propagate.autoApply = updates.autoApply as boolean;
+        if ('manifestUrl' in updates) propagate.manifestUrl = updates.manifestUrl as string;
+        await update.putSettings(propagate);
+      }
+    }
+
+    const next = settingsStore.update(patch);
+    return { ok: true, data: next };
+  });
+}
+
+function validatePatch(body: Record<string, unknown>): { error?: string } {
+  for (const key of Object.keys(body)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      return { error: `Setting "${key}" is not editable at runtime; change it in host.config.json and restart cadre-host.` };
+    }
+    if (!WRITABLE_TOP_KEYS.has(key)) {
+      return { error: `Unknown setting "${key}"` };
+    }
+  }
+  if ('upnpEnabled' in body && typeof body.upnpEnabled !== 'boolean') {
+    return { error: '"upnpEnabled" must be a boolean' };
+  }
+  if ('updates' in body) {
+    if (!body.updates || typeof body.updates !== 'object') {
+      return { error: '"updates" must be an object' };
+    }
+    const updates = body.updates as Record<string, unknown>;
+    for (const key of Object.keys(updates)) {
+      if (!WRITABLE_UPDATES_KEYS.has(key)) {
+        return { error: `Unknown setting "updates.${key}"` };
+      }
+    }
+    if ('autoApply' in updates && typeof updates.autoApply !== 'boolean') {
+      return { error: '"updates.autoApply" must be a boolean' };
+    }
+    if (
+      'manifestUrl' in updates &&
+      typeof updates.manifestUrl !== 'string'
+    ) {
+      return { error: '"updates.manifestUrl" must be a string' };
+    }
+  }
+  return {};
+}

package/src/server/routes/status.ts

@@ -0,0 +1,108 @@
+/**
+ * GET /api/status — aggregated health snapshot used by the SPA's dashboard.
+ *
+ * All inputs are in-memory subsystem state — no disk reads on each call.
+ * The response budget is < 5 ms; favour `getStatus()` over `testReachability()`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { FastifyInstance } from 'fastify';
+
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import type { ManagedNodeInfo } from '../../orchestrator/types.js';
+import type { TrustCircleService } from '../../auth/index.js';
+import type { NatService } from '../../nat/index.js';
+import type { NatStatusSnapshot } from '../../nat/types.js';
+import type { UpdateService } from '../../update/index.js';
+
+const PROCESS_STARTED_AT = process.hrtime.bigint();
+
+export interface StatusRouteOptions {
+  orchestrator: HostProcessOrchestrator;
+  trustCircle: TrustCircleService;
+  nat: NatService;
+  update?: UpdateService;
+}
+
+export interface StatusResponse {
+  service: { name: 'cadre-host'; version: string; uptimeSeconds: number };
+  nodes: Array<{
+    id: string;
+    partyId: string;
+    status: ManagedNodeInfo['status'];
+    profile: ManagedNodeInfo['profile'];
+  }>;
+  trustCircle: { members: number; pending: number };
+  connectivity: NatStatusSnapshot;
+  update?: { available?: string; lastChecked?: string };
+}
+
+export function registerStatusRoute(app: FastifyInstance, opts: StatusRouteOptions): void {
+  const version = readPackageVersion();
+
+  app.get('/api/status', async (): Promise<StatusResponse> => {
+    const nodes = opts.orchestrator.listNodes().map((n) => ({
+      id: n.id,
+      partyId: n.partyId,
+      status: n.status,
+      profile: n.profile,
+    }));
+    const tc = await opts.trustCircle.list();
+    const connectivity = opts.nat.getStatus();
+
+    const response: StatusResponse = {
+      service: {
+        name: 'cadre-host',
+        version,
+        uptimeSeconds: secondsSince(PROCESS_STARTED_AT),
+      },
+      nodes,
+      trustCircle: { members: tc.members.length, pending: tc.pending.length },
+      connectivity,
+    };
+
+    if (opts.update) {
+      const state = await opts.update.getState();
+      const update: { available?: string; lastChecked?: string } = {};
+      if (state.available?.version) update.available = state.available.version;
+      if (state.lastChecked) update.lastChecked = state.lastChecked;
+      response.update = update;
+    }
+
+    return response;
+  });
+}
+
+function secondsSince(start: bigint): number {
+  const now = process.hrtime.bigint();
+  const elapsedNs = now - start;
+  return Number(elapsedNs / 1_000_000_000n);
+}
+
+let cachedVersion: string | null = null;
+function readPackageVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  try {
+    // dist/server/routes/status.js -> ../../../package.json
+    // src/server/routes/status.ts  -> ../../../package.json (vitest)
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      resolve(here, '..', '..', '..', 'package.json'),
+      resolve(here, '..', '..', 'package.json'),
+    ];
+    for (const p of candidates) {
+      try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8')) as { version?: string };
+        if (parsed.version) {
+          cachedVersion = parsed.version;
+          return cachedVersion;
+        }
+      } catch { /* try next */ }
+    }
+  } catch { /* ignore */ }
+  cachedVersion = '0.0.0-unknown';
+  return cachedVersion;
+}

package/src/server/routes/trust-circle.ts

@@ -0,0 +1,49 @@
+/**
+ * Trust-circle HTTP routes — thin adapters around `TrustCircleHandlers`
+ * (`createTrustCircleHandlers(service)`). Side-effects (invite issued,
+ * pending revoked, member removed) emit a `trust-circle-changed` bus
+ * event so the SPA can refresh without polling.
+ *
+ * Mount path: `/auth/*` — the existing CLI (cadre-host invite / trust)
+ * already targets these URLs; do not change them.
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { TrustCircleHandlers } from '../../auth/types.js';
+import type { EventBus } from '../events/bus.js';
+
+export interface TrustCircleRoutesOptions {
+  handlers: TrustCircleHandlers;
+  events: EventBus;
+}
+
+export function registerTrustCircleRoutes(app: FastifyInstance, opts: TrustCircleRoutesOptions): void {
+  const { handlers, events } = opts;
+
+  app.get('/auth/trust-circle', async () => {
+    return handlers.listTrustCircle();
+  });
+
+  app.post('/auth/invites', async (request) => {
+    const body = (request.body ?? {}) as { label?: unknown; ttlMs?: unknown };
+    const label = typeof body.label === 'string' ? body.label : '';
+    const ttlMs = typeof body.ttlMs === 'number' ? body.ttlMs : undefined;
+    const args = ttlMs !== undefined ? { label, ttlMs } : { label };
+    const result = await handlers.postInvite(args);
+    events.publish({ type: 'trust-circle-changed', kind: 'invited' });
+    return result;
+  });
+
+  app.delete<{ Params: { token: string } }>('/auth/invites/:token', async (request) => {
+    await handlers.deleteInvite(request.params.token);
+    events.publish({ type: 'trust-circle-changed', kind: 'revoked' });
+    return { ok: true };
+  });
+
+  app.delete<{ Params: { peerId: string } }>('/auth/members/:peerId', async (request) => {
+    await handlers.deleteMember(request.params.peerId);
+    events.publish({ type: 'trust-circle-changed', kind: 'revoked' });
+    return { ok: true };
+  });
+}

package/src/server/routes/update.ts

@@ -0,0 +1,43 @@
+/**
+ * Update-flow HTTP routes — thin adapters around `UpdateHandlers`
+ * (`createUpdateHandlers(service)`). The /update/apply route publishes
+ * `update-available` for the post-apply state when the new version
+ * differs from the running one.
+ *
+ * Mount path: `/update/*` (matches docs/cadre-host.md).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { UpdateHandlers } from '../../update/index.js';
+import type { EventBus } from '../events/bus.js';
+
+export interface UpdateRoutesOptions {
+  handlers: UpdateHandlers;
+  events: EventBus;
+}
+
+export function registerUpdateRoutes(app: FastifyInstance, opts: UpdateRoutesOptions): void {
+  const { handlers, events } = opts;
+
+  app.get('/update', async () => handlers.getState());
+
+  app.post('/update/apply', async () => {
+    const result = await handlers.postApply();
+    // Apply succeeded — the still-running binary is the *old* one; the new
+    // one becomes live after the service-host restarts. Surface the version
+    // we just applied so the UI can prompt the user to refresh.
+    events.publish({
+      type: 'update-available',
+      version: result.toVersion,
+    });
+    return result;
+  });
+
+  app.get('/update/settings', async () => handlers.getSettings());
+
+  app.put('/update/settings', async (request) => {
+    const body = (request.body ?? {}) as { autoApply?: boolean; manifestUrl?: string };
+    return handlers.putSettings(body);
+  });
+}

package/src/server/server.ts

@@ -0,0 +1,122 @@
+/**
+ * Fastify lifecycle for the cadre-host local UI.
+ *
+ * Bound to `127.0.0.1:<uiPort>` only — never `0.0.0.0`. On `EADDRINUSE`
+ * tries the configured port and then nine consecutive ports. On total
+ * failure the start() promise rejects with a clear message naming every
+ * port that was attempted.
+ *
+ * Shutdown drains with a 5 s timeout, mirroring cadre-provider's pattern.
+ */
+
+import Fastify, { type FastifyInstance } from 'fastify';
+import debug from 'debug';
+
+const log = debug('cadre:host:server');
+
+/** Hard cap on Fastify's drain phase during shutdown. */
+const SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
+/** Inclusive count of ports to try (config port + 9 alternates). */
+const PORT_FALLBACK_TRIES = 10;
+/** Loopback interface; never serve from 0.0.0.0. */
+const LOOPBACK_HOST = '127.0.0.1';
+
+export interface StartServerOptions {
+  /** Preferred port. The server tries this then the next 9 on EADDRINUSE. */
+  preferredPort: number;
+  /**
+   * Test override: when 0, lets the OS pick any free port (skips the
+   * fallback loop). The returned `port` reflects the actual bound port.
+   */
+  forcePort?: 0;
+}
+
+export interface StartedServer {
+  port: number;
+  url: string;
+}
+
+export interface ShutdownOptions {
+  /** Override the 5 s drain timeout (tests). */
+  drainTimeoutMs?: number;
+}
+
+/**
+ * Bind `app` to the loopback interface with port-fallback. Returns the
+ * actually-bound port — the configured port may be in use.
+ */
+export async function startListening(
+  app: FastifyInstance,
+  opts: StartServerOptions,
+): Promise<StartedServer> {
+  if (opts.forcePort === 0) {
+    const address = await app.listen({ host: LOOPBACK_HOST, port: 0 });
+    const port = parsePort(address);
+    return { port, url: `http://${LOOPBACK_HOST}:${port}` };
+  }
+
+  const tried: number[] = [];
+  let lastErr: Error | null = null;
+  for (let i = 0; i < PORT_FALLBACK_TRIES; i++) {
+    const port = opts.preferredPort + i;
+    tried.push(port);
+    try {
+      const address = await app.listen({ host: LOOPBACK_HOST, port });
+      const bound = parsePort(address);
+      if (i > 0) {
+        log('port %d in use; bound on fallback port %d', opts.preferredPort, bound);
+      }
+      return { port: bound, url: `http://${LOOPBACK_HOST}:${bound}` };
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'EADDRINUSE') {
+        throw err;
+      }
+      lastErr = err as Error;
+      log('port %d in use, trying next', port);
+    }
+  }
+  throw new Error(
+    `cadre-host: all ${PORT_FALLBACK_TRIES} candidate ports were in use ` +
+    `(${tried.join(', ')}). Reconfigure uiPort in host.config.json. ` +
+    `Last error: ${lastErr?.message ?? 'unknown'}`,
+  );
+}
+
+/**
+ * Close the server with a hard 5 s drain timeout. Idempotent — safe to call
+ * from a SIGINT/SIGTERM handler that may fire twice.
+ */
+export async function stopListening(
+  app: FastifyInstance,
+  opts: ShutdownOptions = {},
+): Promise<void> {
+  const drainMs = opts.drainTimeoutMs ?? SHUTDOWN_DRAIN_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const drain = app.close();
+  const timeout = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), drainMs);
+  });
+  const outcome = await Promise.race([drain.then(() => 'drained' as const), timeout]);
+  if (timer) clearTimeout(timer);
+  if (outcome === 'timeout') {
+    log('shutdown drain timeout after %dms', drainMs);
+  }
+}
+
+/** Create a bare Fastify instance with the project's logging convention. */
+export function buildFastify(): FastifyInstance {
+  return Fastify({
+    // Stay quiet by default — request-level logs are noisy on a local UI.
+    // Operators can opt in via the `debug` env var (cadre:host:*).
+    logger: false,
+    disableRequestLogging: true,
+  });
+}
+
+function parsePort(address: string): number {
+  // address is e.g. http://127.0.0.1:8765
+  const m = address.match(/:(\d+)\/?$/);
+  if (!m) throw new Error(`cadre-host: unable to parse port from listen address: ${address}`);
+  return Number(m[1]);
+}

package/src/server/settings-store.ts

@@ -0,0 +1,37 @@
+/**
+ * Settings store — read-write facade around `host.config.json` for the
+ * /api/settings route.
+ *
+ * The installer (`6.4.1`) owns the schema (`HostConfigFile` v2). This module
+ * just delegates load/persist to that file's helpers; it exists so route
+ * handlers can read/write without each one re-resolving `configPath(dataDir)`.
+ *
+ * PUT semantics live in routes/settings.ts; this class is purely an I/O
+ * boundary so tests can swap it for an in-memory fake.
+ */
+
+import { configPath } from '../installer/paths.js';
+import { readHostConfig, updateHostConfig, type HostConfigFile } from '../installer/config.js';
+
+export interface HostSettingsStoreOptions {
+  /** Resolved cadre-host data dir. */
+  dataDir: string;
+}
+
+export class HostSettingsStore {
+  private readonly configPath: string;
+
+  constructor(opts: HostSettingsStoreOptions) {
+    this.configPath = configPath(opts.dataDir);
+  }
+
+  /** Read the current host.config.json (runs v1→v2 migration on first read). */
+  read(): HostConfigFile {
+    return readHostConfig(this.configPath);
+  }
+
+  /** Patch and persist. */
+  update(patch: Partial<Omit<HostConfigFile, 'version'>>): HostConfigFile {
+    return updateHostConfig(this.configPath, patch);
+  }
+}