agent-recon 1.0.1

package/installer/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "agent-recon-installer",
+  "version": "1.0.0",
+  "description": "Agent Recon™ — unified CLI installer",
+  "bin": {
+    "agent-recon": "./cli.js"
+  },
+  "main": "cli.js",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0"
+  }
+}

package/installer/steps/api-keys.js

@@ -0,0 +1,59 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const path = require('path');
+const { confirm, password } = require('@inquirer/prompts');
+const ui = require('../ui');
+
+async function run(ctx) {
+  const wantKeys = await confirm({
+    message: 'Configure LLM API keys for analysis features (security chains, insights, prompt coaching)?',
+    default: true,
+  });
+
+  if (!wantKeys) {
+    ui.info('Skipping API key configuration');
+    return { success: true, skipped: true, configured: [] };
+  }
+
+  const configured = [];
+
+  try {
+    const credStore = require(path.join(ctx.installDir, 'server', 'credential-store'));
+
+    const anthropicKey = await password({
+      message: 'Anthropic API key (sk-ant-...):',
+      mask: '*',
+    });
+
+    if (anthropicKey && anthropicKey.trim()) {
+      credStore.setSecret('agent-recon', 'anthropic-api-key', anthropicKey.trim());
+      configured.push('anthropic');
+      ui.ok('Anthropic API key stored');
+    }
+
+    const openaiKey = await password({
+      message: 'OpenAI API key (sk-...) [optional, press Enter to skip]:',
+      mask: '*',
+    });
+
+    if (openaiKey && openaiKey.trim()) {
+      credStore.setSecret('agent-recon', 'openai-api-key', openaiKey.trim());
+      configured.push('openai');
+      ui.ok('OpenAI API key stored');
+    }
+
+    if (configured.length === 0) {
+      ui.info('No API keys provided — analysis features will be disabled');
+    }
+  } catch (err) {
+    ui.warn(`Could not configure API keys: ${err.message}`);
+    return { success: true, configured, error: err.message };
+  }
+
+  return { success: true, configured };
+}
+
+module.exports = { run };

package/installer/steps/directory.js

@@ -0,0 +1,41 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { input } = require('@inquirer/prompts');
+const ui = require('../ui');
+const platform = require('../../server/platform');
+
+function isValidInstallDir(dir) {
+  try {
+    return fs.existsSync(path.join(dir, 'server', 'server.js'));
+  } catch {
+    return false;
+  }
+}
+
+async function run(ctx) {
+  let dir = ctx.installDir || path.resolve(__dirname, '..', '..');
+
+  if (!isValidInstallDir(dir)) {
+    ui.warn(`Default directory not valid: ${dir}`);
+    dir = await input({
+      message: 'Enter the Agent Recon install directory:',
+      validate: val => isValidInstallDir(val) || 'Directory must contain server/server.js',
+    });
+  }
+
+  dir = path.resolve(dir);
+
+  if (platform.detectOS() === 'wsl' && platform.isNtfs(dir)) {
+    ui.warn('Install directory is on NTFS — native addon builds and file watching may be slower');
+  }
+
+  ui.ok(`Install directory: ${dir}`);
+  return { success: true, installDir: dir };
+}
+
+module.exports = { run };

package/installer/steps/env-report.js

@@ -0,0 +1,48 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const { confirm } = require('@inquirer/prompts');
+const ui = require('../ui');
+
+async function run(ctx) {
+  ui.printEnvReport(ctx.envReport);
+
+  const blockers = [];
+  const warnings = [];
+
+  if (!ctx.envReport.pythonVersion) {
+    blockers.push('Python 3 not found — hook scripts require Python');
+  }
+
+  const nodeMajor = parseInt(ctx.envReport.nodeVersion, 10);
+  if (!nodeMajor || nodeMajor < 22) {
+    blockers.push(`Node.js ${ctx.envReport.nodeVersion || 'not found'} — version 22+ required`);
+  }
+
+  if (!ctx.envReport.claudeSettingsExists) {
+    warnings.push('Claude settings.json not found — hooks cannot be registered until Claude Code is run once');
+  }
+
+  if (!ctx.envReport.existingInstall || !ctx.envReport.existingInstall.serverHealthy) {
+    warnings.push('Agent Recon server is not currently running');
+  }
+
+  for (const w of warnings) ui.warn(w);
+  for (const b of blockers) ui.error(b);
+
+  if (blockers.length > 0) {
+    const proceed = await confirm({
+      message: 'Critical issues detected. Continue anyway?',
+      default: false,
+    });
+    if (!proceed) {
+      return { success: false, error: 'Blocked by environment issues' };
+    }
+  }
+
+  return { success: true, blockers, warnings };
+}
+
+module.exports = { run };

package/installer/steps/hooks.js

@@ -0,0 +1,149 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ui = require('../ui');
+const platform = require('../../server/platform');
+
+const EVENTS_PLAIN = [
+  'SessionStart', 'SessionEnd', 'UserPromptSubmit', 'SubagentStart',
+  'SubagentStop', 'Stop', 'TeammateIdle', 'TaskCompleted',
+  // Added in Claude Code v2.1.x
+  'StopFailure', 'PostCompact', 'InstructionsLoaded', 'ConfigChange',
+  'CwdChanged', 'FileChanged', 'WorktreeCreate', 'WorktreeRemove',
+  'TaskCreated', 'ElicitationResult',
+];
+
+const EVENTS_MATCHER = [
+  'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'Notification', 'PreCompact',
+  // Added in Claude Code v2.1.x
+  'PermissionRequest', 'Elicitation',
+];
+
+function _alreadyRegistered(groups, hookCommand) {
+  if (!Array.isArray(groups)) return false;
+  for (const group of groups) {
+    for (const h of (group.hooks || [])) {
+      if (h.command && h.command === hookCommand) return true;
+    }
+  }
+  return false;
+}
+
+function _mergeHooks(settings, hookCommand) {
+  const result = JSON.parse(JSON.stringify(settings || {}));
+  if (!result.hooks) result.hooks = {};
+
+  const hookEntry = { type: 'command', command: hookCommand, async: true, timeout: 10 };
+
+  for (const event of EVENTS_PLAIN) {
+    if (!result.hooks[event]) result.hooks[event] = [];
+    if (!_alreadyRegistered(result.hooks[event], hookCommand)) {
+      result.hooks[event].push({ hooks: [{ ...hookEntry }] });
+    }
+  }
+
+  for (const event of EVENTS_MATCHER) {
+    if (!result.hooks[event]) result.hooks[event] = [];
+    if (!_alreadyRegistered(result.hooks[event], hookCommand)) {
+      result.hooks[event].push({ matcher: '', hooks: [{ ...hookEntry }] });
+    }
+  }
+
+  return result;
+}
+
+function _removeHooks(settings, hookCommand) {
+  const result = JSON.parse(JSON.stringify(settings || {}));
+  if (!result.hooks) return result;
+
+  for (const event of Object.keys(result.hooks)) {
+    if (!Array.isArray(result.hooks[event])) continue;
+    result.hooks[event] = result.hooks[event].filter(group => {
+      const hooks = group.hooks || [];
+      return !hooks.some(h => h.command && h.command === hookCommand);
+    });
+    if (result.hooks[event].length === 0) {
+      delete result.hooks[event];
+    }
+  }
+
+  return result;
+}
+
+function sha256(filePath) {
+  try {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+async function run(ctx) {
+  const osType = ctx.envReport.os;
+  const scriptName = osType === 'wsl' ? 'send-event-wsl.py' : 'send-event.py';
+  const source = path.join(ctx.installDir, '.claude', 'hooks', scriptName);
+  const destDir = path.join(ctx.envReport.home, '.claude', 'hooks');
+  const destination = path.join(destDir, scriptName);
+
+  if (!fs.existsSync(source)) {
+    return { success: false, error: `Hook script not found: ${source}` };
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const srcHash = sha256(source);
+  const dstHash = sha256(destination);
+  if (srcHash !== dstHash) {
+    fs.copyFileSync(source, destination);
+    ui.ok(`Copied ${scriptName} to ${destDir}`);
+  } else {
+    ui.ok(`Hook script already up to date`);
+  }
+
+  if (osType !== 'windows') {
+    try { fs.chmodSync(destination, 0o755); } catch { /* best effort */ }
+  }
+
+  const pythonPath = ctx.envReport.pythonPath || 'python3';
+  const hookCommand = pythonPath + ' ' + destination;
+
+  const settingsPath = path.join(ctx.envReport.home, '.claude', 'settings.json');
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch { /* no existing settings */ }
+
+  const merged = _mergeHooks(settings, hookCommand);
+  const tmpPath = settingsPath + '.tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpPath, settingsPath);
+  ui.ok('Claude settings.json updated with hooks');
+
+  const content = fs.readFileSync(destination, 'utf8');
+  if (content.includes('\r\n')) {
+    ui.warn('Hook script contains CRLF line endings — this may break on Unix. Consider running dos2unix.');
+  }
+
+  const allEvents = [...EVENTS_PLAIN, ...EVENTS_MATCHER];
+  return {
+    success: true,
+    hookCommand,
+    hookScriptDest: destination,
+    hooksAdded: allEvents,
+  };
+}
+
+module.exports = {
+  run,
+  _mergeHooks,
+  _removeHooks,
+  _alreadyRegistered,
+  EVENTS_PLAIN,
+  EVENTS_MATCHER,
+};

package/installer/steps/service.js

@@ -0,0 +1,159 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { confirm } = require('@inquirer/prompts');
+const ui = require('../ui');
+
+async function run(ctx) {
+  const wantService = await confirm({
+    message: 'Install auto-start service so Agent Recon runs on login?',
+    default: true,
+  });
+
+  if (!wantService) {
+    ui.info('Skipping service installation');
+    return { success: true, skipped: true, serviceType: 'none' };
+  }
+
+  const os = ctx.envReport.os;
+
+  try {
+    if (os === 'macos') {
+      return await installMacos(ctx);
+    } else if (os === 'linux') {
+      return await installLinux(ctx);
+    } else if (os === 'windows') {
+      return await installWindows(ctx);
+    } else if (os === 'wsl') {
+      return await handleWsl(ctx);
+    }
+
+    ui.warn(`Unsupported platform for service install: ${os}`);
+    return { success: true, skipped: true, serviceType: 'unknown' };
+  } catch (err) {
+    ui.warn(`Service installation failed: ${err.message}`);
+    return { success: true, serviceType: 'failed', error: err.message };
+  }
+}
+
+async function installMacos(ctx) {
+  const templatePath = path.join(ctx.installDir, 'service', 'com.agent-recon.server.plist');
+  let template = fs.readFileSync(templatePath, 'utf8');
+  template = template.replace(/\{\{INSTALL_DIR\}\}/g, ctx.installDir);
+  template = template.replace(/\{\{HOME\}\}/g, ctx.envReport.home);
+
+  const destDir = path.join(ctx.envReport.home, 'Library', 'LaunchAgents');
+  fs.mkdirSync(destDir, { recursive: true });
+  const destPath = path.join(destDir, 'com.agent-recon.server.plist');
+  fs.writeFileSync(destPath, template, 'utf8');
+  ui.ok(`Wrote launchd plist to ${destPath}`);
+
+  const loadNow = await confirm({ message: 'Load the service now?' });
+  if (loadNow) {
+    try {
+      execFileSync('launchctl', ['load', destPath], { stdio: 'pipe' });
+      ui.ok('Service loaded via launchctl');
+    } catch (err) {
+      ui.warn(`launchctl load failed: ${err.message}`);
+    }
+  }
+
+  return { success: true, serviceType: 'launchd', servicePath: destPath };
+}
+
+async function installLinux(ctx) {
+  const templatePath = path.join(ctx.installDir, 'service', 'agent-recon.service');
+  let template = fs.readFileSync(templatePath, 'utf8');
+  template = template.replace(/\{\{INSTALL_DIR\}\}/g, ctx.installDir);
+
+  const destDir = path.join(ctx.envReport.home, '.config', 'systemd', 'user');
+  fs.mkdirSync(destDir, { recursive: true });
+  const destPath = path.join(destDir, 'agent-recon.service');
+  fs.writeFileSync(destPath, template, 'utf8');
+  ui.ok(`Wrote systemd unit to ${destPath}`);
+
+  try {
+    execFileSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'pipe' });
+    execFileSync('systemctl', ['--user', 'enable', 'agent-recon'], { stdio: 'pipe' });
+    ui.ok('Service enabled via systemctl --user');
+  } catch (err) {
+    ui.warn(`systemctl enable failed: ${err.message}`);
+  }
+
+  const startNow = await confirm({ message: 'Start the service now?' });
+  if (startNow) {
+    try {
+      execFileSync('systemctl', ['--user', 'start', 'agent-recon'], { stdio: 'pipe' });
+      ui.ok('Service started');
+    } catch (err) {
+      ui.warn(`systemctl start failed: ${err.message}`);
+    }
+  }
+
+  return { success: true, serviceType: 'systemd', servicePath: destPath, serviceUnit: 'agent-recon.service' };
+}
+
+async function installWindows(ctx) {
+  if (!ctx.envReport.hasNssm) {
+    ui.warn('NSSM not found — install NSSM (https://nssm.cc) or configure Task Scheduler manually');
+    ui.info('To create a scheduled task: run install-service.ps1 from an admin PowerShell');
+    return { success: true, serviceType: 'manual', servicePath: null };
+  }
+
+  try {
+    const serverDir = path.join(ctx.installDir, 'server');
+    const nodePath = ctx.envReport.nodePath;
+    const startJs = path.join(serverDir, 'start.js');
+    execFileSync('nssm', ['install', 'AgentRecon', nodePath, startJs], { stdio: 'pipe' });
+    execFileSync('nssm', ['set', 'AgentRecon', 'AppDirectory', serverDir], { stdio: 'pipe' });
+    execFileSync('nssm', ['set', 'AgentRecon', 'Start', 'SERVICE_AUTO_START'], { stdio: 'pipe' });
+    ui.ok('Windows service installed via NSSM');
+
+    const startNow = await confirm({ message: 'Start the service now?' });
+    if (startNow) {
+      try {
+        execFileSync('nssm', ['start', 'AgentRecon'], { stdio: 'pipe' });
+        ui.ok('Service started');
+      } catch (err) {
+        ui.warn(`Service start failed: ${err.message}`);
+      }
+    }
+
+    return { success: true, serviceType: 'nssm', servicePath: 'AgentRecon' };
+  } catch (err) {
+    ui.warn(`NSSM service creation failed: ${err.message}`);
+    return { success: true, serviceType: 'failed', error: err.message };
+  }
+}
+
+async function handleWsl(ctx) {
+  ui.info('On WSL, the Agent Recon server should run on the Windows side');
+  ui.info('Use install-service.ps1 in a Windows PowerShell to set up the Windows service');
+
+  const checkStatus = await confirm({ message: 'Check Windows service status?', default: false });
+  if (checkStatus) {
+    try {
+      const ps = '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/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'] });
+      const status = result.trim();
+      if (status) {
+        ui.ok(`Windows AgentRecon service status: ${status}`);
+      } else {
+        ui.info('AgentRecon service not found on Windows');
+      }
+    } catch {
+      ui.info('Could not query Windows service status');
+    }
+  }
+
+  return { success: true, serviceType: 'wsl-deferred' };
+}
+
+module.exports = { run };

package/installer/steps/tls.js

@@ -0,0 +1,104 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const ui = require('../ui');
+
+/**
+ * Installer step — TLS / HTTPS choice.
+ *
+ * Presents three options:
+ *   1. HTTP only (default) — no encryption
+ *   2. Browser-trusted HTTPS via mkcert
+ *   3. Custom certificate — user supplies cert/key paths
+ *
+ * Returns { success, tlsChoice, tlsEnabled, tlsMode, tlsCertPath?, tlsKeyPath? }
+ */
+async function run(ctx) {
+  const { select } = require('@inquirer/prompts');
+  const choice = await select({
+    message: 'How would you like to secure the dashboard?',
+    choices: [
+      { name: 'HTTP only — localhost traffic, no encryption needed', value: 'http' },
+      { name: 'Browser-trusted HTTPS — uses mkcert (one-time admin prompt)', value: 'mkcert' },
+      { name: 'Custom certificate — provide your own CA-signed cert/key paths', value: 'custom' },
+    ],
+    default: ctx.tlsPreselect || 'http',
+  });
+
+  if (choice === 'http') {
+    ui.info('Dashboard will run on HTTP (http://localhost:3131)');
+    return { success: true, tlsChoice: 'http', tlsEnabled: false, tlsMode: 'mkcert' };
+  }
+
+  if (choice === 'mkcert') {
+    return await _handleMkcert();
+  }
+
+  // custom
+  return await _handleCustom();
+}
+
+async function _handleMkcert() {
+  // Check if mkcert is available
+  let mkcertOk = false;
+  try {
+    const { checkMkcert } = require('../../server/tls-setup');
+    const result = checkMkcert();
+    mkcertOk = result.installed;
+    if (mkcertOk) {
+      ui.ok(`mkcert ${result.version} detected`);
+    }
+  } catch {
+    // tls-setup module not loadable — treat as not installed
+  }
+
+  if (!mkcertOk) {
+    const { MKCERT_INSTALL_HINT } = require('../../server/tls-setup');
+    ui.warn('mkcert is not installed.');
+    ui.info(`Install it: ${MKCERT_INSTALL_HINT}`);
+    ui.info('Then run: mkcert -install (one-time, requires admin/sudo)');
+    ui.info('TLS will be enabled in settings — install mkcert and restart the server to activate.');
+    return {
+      success: true,
+      tlsChoice: 'mkcert',
+      tlsEnabled: true,
+      tlsMode: 'mkcert',
+    };
+  }
+
+  ui.ok('mkcert is installed. The server will generate browser-trusted certificates on first start.');
+  ui.info('Run "mkcert -install" if you haven\'t already (one-time, requires admin/sudo).');
+  return {
+    success: true,
+    tlsChoice: 'mkcert',
+    tlsEnabled: true,
+    tlsMode: 'mkcert',
+  };
+}
+
+async function _handleCustom() {
+  const { input } = require('@inquirer/prompts');
+  const certPath = await input({
+    message: 'Path to certificate file (PEM):',
+    validate: v => v.trim().length > 0 || 'Certificate path is required',
+  });
+
+  const keyPath = await input({
+    message: 'Path to private key file (PEM):',
+    validate: v => v.trim().length > 0 || 'Key path is required',
+  });
+
+  ui.ok('Custom certificate paths saved. The server will use these on next start.');
+  return {
+    success: true,
+    tlsChoice: 'custom',
+    tlsEnabled: true,
+    tlsMode: 'custom',
+    tlsCertPath: certPath.trim(),
+    tlsKeyPath: keyPath.trim(),
+  };
+}
+
+module.exports = { run };

package/installer/steps/verify.js

@@ -0,0 +1,117 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+
+'use strict';
+
+const path = require('path');
+const http = require('http');
+const { spawn } = require('child_process');
+const ui = require('../ui');
+
+function httpPost(url, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const data = JSON.stringify(body);
+    const req = http.request({
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+      timeout: 3000,
+    }, res => {
+      let buf = '';
+      res.on('data', chunk => { buf += chunk; });
+      res.on('end', () => resolve({ status: res.statusCode, body: buf }));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    req.write(data);
+    req.end();
+  });
+}
+
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const req = http.get({
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname,
+      timeout: 2000,
+    }, res => {
+      let buf = '';
+      res.on('data', chunk => { buf += chunk; });
+      res.on('end', () => resolve({ status: res.statusCode, body: buf }));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+  });
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function isServerRunning() {
+  try {
+    const res = await httpGet('http://localhost:3131/health');
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+async function run(ctx) {
+  let serverRunning = await isServerRunning();
+
+  if (!serverRunning) {
+    ui.info('Server not running — attempting to start...');
+    const serverDir = path.join(ctx.installDir, 'server');
+    try {
+      const child = spawn('node', ['start.js'], {
+        cwd: serverDir,
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+
+      for (let i = 0; i < 5; i++) {
+        await sleep(1000);
+        serverRunning = await isServerRunning();
+        if (serverRunning) break;
+      }
+    } catch (err) {
+      ui.warn(`Could not start server: ${err.message}`);
+    }
+  }
+
+  if (!serverRunning) {
+    ui.warn('Server did not start — verification skipped');
+    return { success: true, serverRunning: false, error: 'Server not reachable' };
+  }
+
+  ui.ok('Server is running');
+
+  try {
+    const testPayload = {
+      session_id: 'installer-verify',
+      hook_event_name: 'SessionStart',
+      payload: { type: 'installer-test' },
+    };
+
+    const res = await httpPost('http://localhost:3131/event', testPayload);
+    if (res.status === 200) {
+      ui.ok('Test event sent and accepted');
+      return { success: true, serverRunning: true };
+    }
+
+    ui.warn(`Test event returned status ${res.status}`);
+    return { success: true, serverRunning: true, error: `Unexpected status: ${res.status}` };
+  } catch (err) {
+    ui.warn(`Test event failed: ${err.message}`);
+    return { success: true, serverRunning: true, error: err.message };
+  }
+}
+
+module.exports = { run };