agent-recon 1.0.1

package/installer/detect.js

@@ -0,0 +1,355 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+/**
+ * Agent Recon Installer — Environment Detection (Task 8.1)
+ *
+ * Detects OS, arch, Node, Python, Claude Code presence, existing Agent Recon
+ * installation, credential backend, and platform capabilities.
+ *
+ * Pure detection logic is extracted into testable _-prefixed helpers.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const crypto = require('crypto');
+
+// Reuse platform.js from the server module for consistent OS detection
+const platform = require('../server/platform');
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const HOOK_SCRIPT_MARKER = 'Agent Recon';
+
+// ── Pure helpers (testable) ─────────────────────────────────────────────────
+
+/**
+ * SHA-256 hash of a file's contents.
+ * @param {string} filePath
+ * @returns {string|null} hex digest, or null if file doesn't exist
+ */
+function _hashFile(filePath) {
+  try {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count how many Agent Recon hook events are registered in a settings object.
+ * @param {object} settings — parsed ~/.claude/settings.json
+ * @param {string} hookCommand — the hook command string to search for
+ * @returns {number} count of events with a matching hook
+ */
+function _countRegisteredHooks(settings, hookCommand) {
+  if (!settings || !settings.hooks) return 0;
+  let count = 0;
+  for (const [, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      const hooks = group.hooks || [];
+      for (const h of hooks) {
+        if (h.command && h.command.includes(hookCommand)) {
+          count++;
+          break; // count the event once even if registered multiple times
+        }
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Parse settings.json to find the Agent Recon hook command string.
+ * @param {object} settings — parsed settings.json
+ * @returns {string|null} the hook command, or null if not found
+ */
+function _findHookCommand(settings) {
+  if (!settings || !settings.hooks) return null;
+  for (const [, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const h of (group.hooks || [])) {
+        if (h.command && (h.command.includes('send-event.py') || h.command.includes('send-event-wsl.py'))) {
+          return h.command;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the hook script destination path from a hook command string.
+ * e.g. "python3 /home/user/.claude/hooks/send-event.py" → "/home/user/.claude/hooks/send-event.py"
+ * @param {string} hookCommand
+ * @returns {string|null}
+ */
+function _hookScriptFromCommand(hookCommand) {
+  if (!hookCommand) return null;
+  const parts = hookCommand.split(' ');
+  // The script path is the last part that ends with .py
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (parts[i].endsWith('.py')) return parts[i];
+  }
+  return null;
+}
+
+// ── Exec helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Find a working Python 3 executable.
+ * Tries python3, python, py in order (matching setup.ps1 logic).
+ * @returns {{path: string, version: string}|null}
+ */
+function findPython() {
+  const candidates = process.platform === 'win32'
+    ? ['python', 'py', 'python3']
+    : ['python3', 'python'];
+
+  for (const cmd of candidates) {
+    try {
+      const ver = execFileSync(cmd, ['--version'], {
+        encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      if (/Python 3/i.test(ver)) {
+        return { path: cmd, version: ver.replace(/^Python\s*/i, '') };
+      }
+    } catch { /* not found or wrong version */ }
+  }
+  return null;
+}
+
+/**
+ * Get the current Node.js info.
+ * @returns {{path: string, version: string}}
+ */
+function findNode() {
+  return {
+    path: process.execPath,
+    version: process.version.replace(/^v/, ''),
+  };
+}
+
+/**
+ * Path to Claude Code's user-global settings file.
+ * @returns {string}
+ */
+function findClaudeSettings() {
+  return path.join(platform.homedir(), '.claude', 'settings.json');
+}
+
+/**
+ * Check if the Agent Recon server is healthy.
+ * @param {number} [port=3131]
+ * @returns {Promise<{ok: boolean, eventCount: number, dbEventCount: number, clients: number}|null>}
+ */
+function checkServerHealth(port) {
+  const p = port || 3131;
+  return new Promise(resolve => {
+    const http = require('http');
+    const req = http.get(`http://localhost:${p}/health`, { timeout: 2000 }, res => {
+      let body = '';
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(body)); } catch { resolve(null); }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+// ── Service detection ───────────────────────────────────────────────────────
+
+function _hasCommand(cmd) {
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], {
+      encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _serviceInstalled(osType) {
+  try {
+    if (osType === 'macos') {
+      const plist = path.join(platform.homedir(), 'Library', 'LaunchAgents', 'com.agent-recon.server.plist');
+      return fs.existsSync(plist);
+    }
+    if (osType === 'linux') {
+      const unit = path.join(platform.homedir(), '.config', 'systemd', 'user', 'agent-recon.service');
+      return fs.existsSync(unit);
+    }
+    if (osType === 'windows' || osType === 'wsl') {
+      // Check NSSM service — best effort
+      try {
+        const ps = osType === 'wsl'
+          ? '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe'
+          : 'powershell.exe';
+        const result = execFileSync(ps, ['-NoProfile', '-Command',
+          'Get-Service AgentRecon -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Status'],
+          { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+        return result.trim().length > 0;
+      } catch { return false; }
+    }
+  } catch { /* ignore */ }
+  return false;
+}
+
+// ── Existing install detection ──────────────────────────────────────────────
+
+/**
+ * Detect an existing Agent Recon installation.
+ * Checks manifest first, falls back to heuristic detection.
+ * @returns {object|null}
+ */
+function findExistingInstall() {
+  const osType = platform.detectOS();
+  const confDir = platform.configDir();
+  const manifestFile = path.join(confDir, 'manifest.json');
+
+  // ── Try manifest first
+  if (fs.existsSync(manifestFile)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+      const hookDest = manifest.hookScript && manifest.hookScript.destination;
+      const hookSrc = manifest.hookScript && manifest.hookScript.source;
+      const hookCurrent = hookDest && hookSrc
+        ? _hashFile(hookDest) === _hashFile(hookSrc)
+        : false;
+
+      const settingsPath = manifest.claudeSettingsPath || findClaudeSettings();
+      let hooksRegistered = 0;
+      if (fs.existsSync(settingsPath)) {
+        try {
+          const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+          const hookCmd = manifest.hookCommand || 'send-event';
+          hooksRegistered = _countRegisteredHooks(settings, hookCmd);
+        } catch { /* corrupt settings */ }
+      }
+
+      const svcInstalled = _serviceInstalled(osType);
+
+      return {
+        installDir: manifest.installDir,
+        version: manifest.version,
+        hookScriptPath: hookDest,
+        hookScriptCurrent: hookCurrent,
+        hooksRegistered,
+        serviceInstalled: svcInstalled,
+        serviceRunning: false, // filled by caller via checkServerHealth
+        serverHealthy: false,  // filled by caller
+        manifestPath: manifestFile,
+        dbPath: manifest.dbPath || null,
+        dbSizeBytes: _fileSize(manifest.dbPath),
+      };
+    } catch { /* corrupt manifest, fall through to heuristic */ }
+  }
+
+  // ── Heuristic detection (no manifest)
+  const settingsPath = findClaudeSettings();
+  if (!fs.existsSync(settingsPath)) return null;
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch { return null; }
+
+  const hookCommand = _findHookCommand(settings);
+  if (!hookCommand) return null;
+
+  const hookScriptPath = _hookScriptFromCommand(hookCommand);
+  const hooksRegistered = _countRegisteredHooks(settings, hookCommand);
+  const svcInstalled = _serviceInstalled(osType);
+
+  return {
+    installDir: null, // unknown without manifest
+    version: null,
+    hookScriptPath,
+    hookScriptCurrent: false, // can't determine without knowing source
+    hooksRegistered,
+    serviceInstalled: svcInstalled,
+    serviceRunning: false,
+    serverHealthy: false,
+    manifestPath: null,
+    dbPath: null,
+    dbSizeBytes: 0,
+  };
+}
+
+function _fileSize(filePath) {
+  if (!filePath) return 0;
+  try { return fs.statSync(filePath).size; } catch { return 0; }
+}
+
+// ── Main detection ──────────────────────────────────────────────────────────
+
+/**
+ * Run full environment detection.
+ * @returns {Promise<object>} EnvReport
+ */
+async function detectEnv() {
+  const osType = platform.detectOS();
+  const node = findNode();
+  const python = findPython();
+  const claudeSettingsPath = findClaudeSettings();
+  const claudeSettingsExists = fs.existsSync(claudeSettingsPath);
+  const home = platform.homedir();
+  const confDir = platform.configDir();
+  const existing = findExistingInstall();
+
+  // Check server health (async)
+  const health = await checkServerHealth();
+  if (existing && health && health.ok) {
+    existing.serverHealthy = true;
+    existing.serviceRunning = true;
+  }
+
+  return {
+    os: osType,
+    arch: process.arch,
+    nodeVersion: node.version,
+    nodePath: node.path,
+    pythonVersion: python ? python.version : null,
+    pythonPath: python ? python.path : null,
+    home,
+    configDir: confDir,
+    claudeSettingsPath,
+    claudeSettingsExists,
+    claudeHooksDir: path.join(home, '.claude', 'hooks'),
+    existingInstall: existing,
+    credentialBackend: platform.credentialBackend(),
+    // Platform capabilities
+    hasNssm: osType === 'windows' ? _hasCommand('nssm') : false,
+    hasSystemctl: (osType === 'linux') ? _hasCommand('systemctl') : false,
+    hasLaunchctl: osType === 'macos' ? _hasCommand('launchctl') : false,
+    hasSecretTool: osType === 'linux' ? _hasCommand('secret-tool') : false,
+    hasCurl: _hasCommand('curl'),
+  };
+}
+
+// ── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  detectEnv,
+  findClaudeSettings,
+  findPython,
+  findNode,
+  findExistingInstall,
+  checkServerHealth,
+  // Testable pure helpers
+  _hashFile,
+  _countRegisteredHooks,
+  _findHookCommand,
+  _hookScriptFromCommand,
+  _serviceInstalled,
+  _fileSize,
+};

package/installer/install.js

@@ -0,0 +1,195 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+/**
+ * Agent Recon Installer — Guided Install Orchestrator (Task 8.2)
+ *
+ * Runs steps in sequence: welcome → env-report → directory → hooks →
+ * api-keys → service → verify → write manifest.
+ */
+
+const path = require('path');
+const ui   = require('./ui');
+const manifest = require('./manifest');
+
+const welcome   = require('./steps/welcome');
+const envReport = require('./steps/env-report');
+const directory = require('./steps/directory');
+const hooks     = require('./steps/hooks');
+const apiKeys   = require('./steps/api-keys');
+const service   = require('./steps/service');
+const tls       = require('./steps/tls');
+const verify    = require('./steps/verify');
+
+const TOTAL_STEPS = 8;
+
+/**
+ * Run the guided install flow.
+ * @param {object} env — from detect.detectEnv()
+ * @param {object} opts — {version, force}
+ */
+async function install(env, opts) {
+  const ctx = {
+    envReport: env,
+    installDir: null,
+    version: opts.version || '1.0.0',
+    force: opts.force || false,
+    tlsPreselect: opts.tls ? 'mkcert' : null,
+    results: {},
+  };
+
+  // ── Step 1: Welcome + EULA ──────────────────────────────────────────────
+  ui.step(1, TOTAL_STEPS, 'Welcome & License');
+  const welcomeResult = await welcome.run(ctx);
+  if (!welcomeResult.success) {
+    ui.error(welcomeResult.error || 'Installation cancelled.');
+    return;
+  }
+  ctx.results.welcome = welcomeResult;
+
+  // ── Step 2: Environment Report ──────────────────────────────────────────
+  ui.step(2, TOTAL_STEPS, 'Environment Detection');
+  const envResult = await envReport.run(ctx);
+  if (!envResult.success) {
+    ui.error(envResult.error || 'Installation cancelled.');
+    return;
+  }
+  ctx.results.env = envResult;
+
+  // ── Step 3: Installation Directory ──────────────────────────────────────
+  ui.step(3, TOTAL_STEPS, 'Installation Directory');
+  const dirResult = await directory.run(ctx);
+  if (!dirResult.success) {
+    ui.error(dirResult.error || 'Installation cancelled.');
+    return;
+  }
+  ctx.installDir = dirResult.installDir;
+  ctx.results.directory = dirResult;
+
+  // ── Step 4: Hook Installation ───────────────────────────────────────────
+  ui.step(4, TOTAL_STEPS, 'Hook Installation');
+  const hooksResult = await hooks.run(ctx);
+  if (!hooksResult.success) {
+    ui.error(hooksResult.error || 'Hook installation failed.');
+    return;
+  }
+  ctx.results.hooks = hooksResult;
+
+  // ── Step 5: API Key Configuration (optional) ───────────────────────────
+  ui.step(5, TOTAL_STEPS, 'API Key Configuration');
+  try {
+    const keysResult = await apiKeys.run(ctx);
+    ctx.results.apiKeys = keysResult;
+  } catch (err) {
+    ui.warn(`API key configuration failed: ${err.message}`);
+    ctx.results.apiKeys = { success: true, skipped: true, configured: [] };
+  }
+
+  // ── Step 6: Auto-Start Service (optional) ──────────────────────────────
+  ui.step(6, TOTAL_STEPS, 'Auto-Start Service');
+  try {
+    const svcResult = await service.run(ctx);
+    ctx.results.service = svcResult;
+  } catch (err) {
+    ui.warn(`Service setup failed: ${err.message}`);
+    ctx.results.service = { success: true, skipped: true, serviceType: 'none' };
+  }
+
+  // ── Step 7: TLS / HTTPS ────────────────────────────────────────────────
+  ui.step(7, TOTAL_STEPS, 'TLS / HTTPS');
+  try {
+    // Pre-select mkcert if --tls flag was passed
+    if (ctx.force && ctx.tlsPreselect) ctx.tlsPreselect = ctx.tlsPreselect;
+    const tlsResult = await tls.run(ctx);
+    ctx.results.tls = tlsResult;
+  } catch (err) {
+    ui.warn(`TLS setup skipped: ${err.message}`);
+    ctx.results.tls = { success: true, tlsChoice: 'http', tlsEnabled: false, tlsMode: 'mkcert' };
+  }
+
+  // ── Step 8: Verification ───────────────────────────────────────────────
+  ui.step(8, TOTAL_STEPS, 'Verification');
+  try {
+    const verifyResult = await verify.run(ctx);
+    ctx.results.verify = verifyResult;
+  } catch (err) {
+    ui.warn(`Verification failed: ${err.message}`);
+    ctx.results.verify = { success: false, error: err.message };
+  }
+
+  // ── Write manifest ─────────────────────────────────────────────────────
+  const platform = require('../server/platform');
+  const crypto   = require('crypto');
+  const fs       = require('fs');
+
+  // Generate a unique install ID (UUID v4, not derived from PII)
+  const installationId = crypto.randomUUID();
+
+  let hookSha256 = null;
+  if (ctx.results.hooks && ctx.results.hooks.hookScriptDest) {
+    try {
+      const buf = fs.readFileSync(ctx.results.hooks.hookScriptDest);
+      hookSha256 = crypto.createHash('sha256').update(buf).digest('hex');
+    } catch { /* best effort */ }
+  }
+
+  const m = manifest.createManifest({
+    version: ctx.version,
+    os: env.os,
+    arch: env.arch,
+    installDir: ctx.installDir,
+    hookScriptSource: ctx.results.hooks
+      ? path.join(ctx.installDir, '.claude', 'hooks',
+          env.os === 'wsl' ? 'send-event-wsl.py' : 'send-event.py')
+      : null,
+    hookScriptDest: ctx.results.hooks ? ctx.results.hooks.hookScriptDest : null,
+    hookScriptSha256: hookSha256,
+    hooksRegistered: ctx.results.hooks ? ctx.results.hooks.hooksAdded : [],
+    hookCommand: ctx.results.hooks ? ctx.results.hooks.hookCommand : null,
+    claudeSettingsPath: env.claudeSettingsPath,
+    serviceType: ctx.results.service ? ctx.results.service.serviceType || 'none' : 'none',
+    serviceUnit: ctx.results.service ? ctx.results.service.serviceUnit || null : null,
+    servicePath: ctx.results.service ? ctx.results.service.servicePath || null : null,
+    apiKeysConfigured: ctx.results.apiKeys ? ctx.results.apiKeys.configured || [] : [],
+    credentialBackend: env.credentialBackend,
+    dbPath: path.join(ctx.installDir, 'data', 'agent-recon.db'),
+    credentialDir: path.join(platform.configDir(), 'credentials'),
+    installationId,
+    telemetryEnabled: ctx.results.welcome ? ctx.results.welcome.telemetryEnabled : false,
+    eulaAccepted: true,
+    tlsEnabled: ctx.results.tls ? ctx.results.tls.tlsEnabled : false,
+    tlsMode: ctx.results.tls ? ctx.results.tls.tlsMode : 'mkcert',
+    tlsCertPath: ctx.results.tls ? ctx.results.tls.tlsCertPath || null : null,
+    tlsKeyPath: ctx.results.tls ? ctx.results.tls.tlsKeyPath || null : null,
+  });
+
+  manifest.writeManifest(m);
+  ui.ok('Installation manifest saved');
+
+  // ── Summary ────────────────────────────────────────────────────────────
+  console.log('');
+  ui.divider();
+  ui.ok(`Agent Recon v${ctx.version} installed successfully!`);
+  ui.divider();
+  ui.info(`Install directory: ${ctx.installDir}`);
+  ui.info(`Hooks: ${ctx.results.hooks ? ctx.results.hooks.hooksAdded.length : 0} events registered`);
+  ui.info(`Service: ${ctx.results.service ? ctx.results.service.serviceType || 'none' : 'none'}`);
+  ui.info(`Install ID: ${installationId}`);
+  ui.info(`Telemetry: ${ctx.results.welcome.telemetryEnabled ? 'enabled' : 'disabled'}`);
+  ui.info(`TLS: ${ctx.results.tls ? ctx.results.tls.tlsChoice : 'http'}`);
+  ui.info(`API keys: ${(ctx.results.apiKeys && ctx.results.apiKeys.configured || []).join(', ') || 'none'}`);
+  if (ctx.results.verify && ctx.results.verify.success) {
+    ui.ok('Server verified and running');
+    const dashUrl = ctx.results.tls && ctx.results.tls.tlsEnabled
+      ? 'https://localhost:3132' : 'http://localhost:3131';
+    ui.info(`Open ${dashUrl} in your browser to view the dashboard`);
+  } else {
+    ui.warn('Server verification did not complete — start manually:');
+    ui.info(`  cd ${ctx.installDir}/server && node start.js`);
+  }
+  ui.divider();
+}
+
+module.exports = install;

package/installer/manifest.js

@@ -0,0 +1,140 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+/**
+ * Agent Recon Installer — Installation Manifest
+ *
+ * Records what was installed, where, and when. Single source of truth
+ * for upgrade and uninstall operations.
+ *
+ * Stored at platform.configDir()/manifest.json:
+ *   macOS:     ~/Library/Application Support/agent-recon/manifest.json
+ *   Windows:   %APPDATA%/agent-recon/manifest.json
+ *   Linux/WSL: ~/.config/agent-recon/manifest.json
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const platform = require('../server/platform');
+
+const MANIFEST_VERSION = 2;
+
+// ── Path ────────────────────────────────────────────────────────────────────
+
+/**
+ * Absolute path to the manifest file.
+ * @returns {string}
+ */
+function manifestPath() {
+  return path.join(platform.configDir(), 'manifest.json');
+}
+
+// ── Read ────────────────────────────────────────────────────────────────────
+
+/**
+ * Read and parse the manifest file.
+ * @returns {object|null} parsed manifest, or null if missing/corrupt
+ */
+function readManifest() {
+  const p = manifestPath();
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    const manifest = JSON.parse(raw);
+    if (!manifest || typeof manifest !== 'object') return null;
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+// ── Write ───────────────────────────────────────────────────────────────────
+
+/**
+ * Write the manifest to disk atomically.
+ * Creates the config directory if needed.
+ * @param {object} manifest
+ */
+function writeManifest(manifest) {
+  const p = manifestPath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+
+  const data = JSON.stringify(manifest, null, 2) + '\n';
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, data, 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+// ── Delete ──────────────────────────────────────────────────────────────────
+
+/**
+ * Delete the manifest file. No-op if it doesn't exist.
+ */
+function deleteManifest() {
+  const p = manifestPath();
+  try { fs.unlinkSync(p); } catch { /* not found — fine */ }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a fresh manifest object with required fields.
+ * @param {object} opts
+ * @returns {object}
+ */
+function createManifest(opts) {
+  const now = new Date().toISOString();
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    installedAt: now,
+    updatedAt: now,
+    version: opts.version || '1.0.0',
+    os: opts.os || platform.detectOS(),
+    arch: opts.arch || process.arch,
+    installDir: opts.installDir,
+    serverDir: opts.serverDir || path.join(opts.installDir, 'server'),
+    hookScript: {
+      source: opts.hookScriptSource || null,
+      destination: opts.hookScriptDest || null,
+      sha256: opts.hookScriptSha256 || null,
+    },
+    hooksRegistered: opts.hooksRegistered || [],
+    hookCommand: opts.hookCommand || null,
+    claudeSettingsPath: opts.claudeSettingsPath || null,
+    service: {
+      type: opts.serviceType || 'none',
+      unit: opts.serviceUnit || null,
+      path: opts.servicePath || null,
+    },
+    apiKeys: {
+      configured: opts.apiKeysConfigured || [],
+      backend: opts.credentialBackend || platform.credentialBackend(),
+    },
+    dbPath: opts.dbPath || null,
+    credentialDir: opts.credentialDir || null,
+    installation_id: opts.installationId || null,
+    tls: {
+      enabled: opts.tlsEnabled || false,
+      mode: opts.tlsMode || 'mkcert',
+      certPath: opts.tlsCertPath || null,
+      keyPath: opts.tlsKeyPath || null,
+    },
+    settings: {
+      telemetry_enabled: opts.telemetryEnabled || false,
+      eula_accepted: opts.eulaAccepted || false,
+      eula_accepted_at: opts.eulaAccepted ? now : null,
+    },
+  };
+}
+
+// ── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  MANIFEST_VERSION,
+  manifestPath,
+  readManifest,
+  writeManifest,
+  deleteManifest,
+  createManifest,
+};