agent-recon 1.0.1

package/install-service.ps1

@@ -0,0 +1,302 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Install / uninstall / query the Agent Recon Windows Service.
+
+.DESCRIPTION
+    Uses NSSM (Non-Sucking Service Manager) to wrap the Node.js process as a
+    proper Windows Service that responds to service-control messages. NSSM must
+    be installed first (e.g. `choco install nssm` or download from https://nssm.cc).
+
+    The service runs:  node <repo>\server\start.js
+    Working directory: <repo>\server
+    Service name:      AgentRecon
+
+.PARAMETER Uninstall
+    Remove the AgentRecon service.
+
+.PARAMETER Status
+    Show current service status and configuration.
+
+.EXAMPLE
+    # Install (run as Administrator)
+    .\install-service.ps1
+
+    # Check status
+    .\install-service.ps1 -Status
+
+    # Remove
+    .\install-service.ps1 -Uninstall
+#>
+
+[CmdletBinding(DefaultParameterSetName = 'Install')]
+param(
+    [Parameter(ParameterSetName = 'Uninstall')]
+    [switch]$Uninstall,
+
+    [Parameter(ParameterSetName = 'Status')]
+    [switch]$Status
+)
+
+$ErrorActionPreference = 'Stop'
+
+# -- Constants ----------------------------------------------------------------
+$ServiceName   = 'AgentRecon'
+$DisplayName   = 'Agent Recon - Claude Code Observability'
+$Description   = 'Real-time observability dashboard for Claude Code sessions'
+$RepoRoot      = $PSScriptRoot
+$ServerDir     = Join-Path $RepoRoot 'server'
+$StartScript   = Join-Path $ServerDir 'start.js'
+
+# -- Helpers ------------------------------------------------------------------
+
+function Write-Info  { param([string]$Msg) Write-Host "  [INFO]  $Msg" -ForegroundColor Cyan }
+function Write-Ok    { param([string]$Msg) Write-Host "  [OK]    $Msg" -ForegroundColor Green }
+function Write-Warn  { param([string]$Msg) Write-Host "  [WARN]  $Msg" -ForegroundColor Yellow }
+function Write-Err   { param([string]$Msg) Write-Host "  [FAIL]  $Msg" -ForegroundColor Red }
+
+function Assert-Admin {
+    $identity  = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $principal = New-Object Security.Principal.WindowsPrincipal($identity)
+    if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+        Write-Warn 'Not running as Administrator. Relaunching elevated...'
+        $argList = '-ExecutionPolicy Bypass -File "' + $PSCommandPath + '"'
+        if ($Uninstall) { $argList += ' -Uninstall' }
+        if ($Status)    { $argList += ' -Status' }
+        Start-Process powershell.exe -ArgumentList $argList -Verb RunAs
+        exit 0
+    }
+}
+
+function Find-Nssm {
+    $nssm = Get-Command nssm -ErrorAction SilentlyContinue
+    if ($nssm) { return $nssm.Source }
+
+    # Common Chocolatey path
+    $chocoPath = Join-Path $env:ProgramData 'chocolatey\bin\nssm.exe'
+    if (Test-Path $chocoPath) { return $chocoPath }
+
+    return $null
+}
+
+function Find-Node {
+    $node = Get-Command node -ErrorAction SilentlyContinue
+    if (-not $node) {
+        Write-Err 'Node.js not found on PATH. Install Node.js 22+ and try again.'
+        exit 1
+    }
+    $ver = (& $node.Source --version 2>&1).ToString().Trim()
+    Write-Info "Node.js: $($node.Source) ($ver)"
+    return $node.Source
+}
+
+# -- Status -------------------------------------------------------------------
+
+if ($Status) {
+    Write-Host ''
+    Write-Host "Agent Recon Service Status" -ForegroundColor Cyan
+    Write-Host ('-' * 40) -ForegroundColor Cyan
+
+    $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+    if (-not $svc) {
+        Write-Warn "Service '$ServiceName' is not installed."
+        Write-Host ''
+        exit 0
+    }
+
+    Write-Info "Name:         $($svc.Name)"
+    Write-Info "Display Name: $($svc.DisplayName)"
+    Write-Info "Status:       $($svc.Status)"
+    Write-Info "Start Type:   $($svc.StartType)"
+
+    $nssmExe = Find-Nssm
+    if ($nssmExe) {
+        try {
+            $appPath = (& $nssmExe get $ServiceName Application 2>&1).ToString().Trim()
+            $appDir  = (& $nssmExe get $ServiceName AppDirectory 2>&1).ToString().Trim()
+            $appArgs = (& $nssmExe get $ServiceName AppParameters 2>&1).ToString().Trim()
+            Write-Info "Application:  $appPath"
+            Write-Info "Arguments:    $appArgs"
+            Write-Info "Working Dir:  $appDir"
+        } catch { }
+
+        try {
+            $stdoutLog = (& $nssmExe get $ServiceName AppStdout 2>&1).ToString().Trim()
+            $stderrLog = (& $nssmExe get $ServiceName AppStderr 2>&1).ToString().Trim()
+            if ($stdoutLog) { Write-Info "Stdout Log:   $stdoutLog" }
+            if ($stderrLog) { Write-Info "Stderr Log:   $stderrLog" }
+        } catch { }
+    }
+
+    Write-Host ''
+    Write-Host 'Quick commands:' -ForegroundColor Cyan
+    Write-Host "  Start:   Start-Service $ServiceName"
+    Write-Host "  Stop:    Stop-Service $ServiceName"
+    Write-Host "  Restart: Restart-Service $ServiceName"
+    Write-Host ''
+    exit 0
+}
+
+# -- Require admin for install / uninstall ------------------------------------
+Assert-Admin
+
+# -- Uninstall ----------------------------------------------------------------
+
+if ($Uninstall) {
+    Write-Host ''
+    Write-Host "Removing Agent Recon Service" -ForegroundColor Cyan
+    Write-Host ('-' * 40) -ForegroundColor Cyan
+
+    $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+    if (-not $svc) {
+        Write-Warn "Service '$ServiceName' is not installed. Nothing to remove."
+        Write-Host ''
+        exit 0
+    }
+
+    # Stop the service if running
+    if ($svc.Status -eq 'Running') {
+        Write-Info 'Stopping service...'
+        Stop-Service -Name $ServiceName -Force
+        Start-Sleep -Seconds 2
+        Write-Ok 'Service stopped.'
+    }
+
+    $nssmExe = Find-Nssm
+    if ($nssmExe) {
+        Write-Info 'Removing service via NSSM...'
+        & $nssmExe remove $ServiceName confirm
+    } else {
+        Write-Info 'Removing service via sc.exe...'
+        & sc.exe delete $ServiceName
+    }
+
+    # Verify removal
+    $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+    if ($svc) {
+        Write-Err "Service still exists. A reboot may be required to complete removal."
+    } else {
+        Write-Ok "Service '$ServiceName' removed successfully."
+    }
+    Write-Host ''
+    exit 0
+}
+
+# -- Install ------------------------------------------------------------------
+
+Write-Host ''
+Write-Host 'Installing Agent Recon as Windows Service' -ForegroundColor Cyan
+Write-Host ('-' * 48) -ForegroundColor Cyan
+
+# Check prerequisites
+$NodeExe = Find-Node
+
+if (-not (Test-Path $StartScript)) {
+    Write-Err "start.js not found at: $StartScript"
+    Write-Err 'Run this script from the agent-recon repo root.'
+    exit 1
+}
+
+# Check for existing service
+$existingSvc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+if ($existingSvc) {
+    Write-Warn "Service '$ServiceName' already exists (Status: $($existingSvc.Status))."
+    Write-Warn "Run  .\install-service.ps1 -Uninstall  first, then re-install."
+    exit 1
+}
+
+# Find NSSM
+$NssmExe = Find-Nssm
+
+if (-not $NssmExe) {
+    Write-Err 'NSSM (Non-Sucking Service Manager) not found.'
+    Write-Host ''
+    Write-Host '  Windows services must respond to Service Control Manager (SCM) messages.' -ForegroundColor Yellow
+    Write-Host '  Node.js does not do this natively, so a service wrapper is required.' -ForegroundColor Yellow
+    Write-Host ''
+    Write-Host '  Install NSSM using one of these methods:' -ForegroundColor Cyan
+    Write-Host '    choco install nssm          # via Chocolatey' -ForegroundColor White
+    Write-Host '    scoop install nssm           # via Scoop' -ForegroundColor White
+    Write-Host '    winget install nssm           # via WinGet' -ForegroundColor White
+    Write-Host '    https://nssm.cc/download      # manual download' -ForegroundColor White
+    Write-Host ''
+    Write-Host '  After installing NSSM, re-run this script.' -ForegroundColor Cyan
+    Write-Host ''
+    Write-Host '  Alternative: manual service setup without NSSM' -ForegroundColor Cyan
+    Write-Host '  ------------------------------------------------' -ForegroundColor Cyan
+    Write-Host '  If you prefer not to install NSSM, you can run Agent Recon at startup' -ForegroundColor Yellow
+    Write-Host '  using Task Scheduler instead:' -ForegroundColor Yellow
+    Write-Host ''
+    Write-Host "    schtasks /create /tn `"AgentRecon`" /tr `"'$NodeExe' '$StartScript'`" /sc onlogon /rl highest" -ForegroundColor White
+    Write-Host ''
+    Write-Host '  Or add a shortcut to:  shell:startup' -ForegroundColor White
+    Write-Host ''
+    exit 1
+}
+
+Write-Info "NSSM: $NssmExe"
+
+# Create log directory
+$LogDir = Join-Path $RepoRoot 'data' 'logs'
+if (-not (Test-Path $LogDir)) {
+    New-Item -ItemType Directory -Path $LogDir -Force | Out-Null
+    Write-Ok "Created log directory: $LogDir"
+}
+
+$StdoutLog = Join-Path $LogDir 'service-stdout.log'
+$StderrLog = Join-Path $LogDir 'service-stderr.log'
+
+# Install the service via NSSM
+Write-Info 'Creating service via NSSM...'
+& $NssmExe install $ServiceName $NodeExe $StartScript
+if ($LASTEXITCODE -ne 0) {
+    Write-Err "NSSM install failed (exit code $LASTEXITCODE)."
+    exit 1
+}
+
+# Configure service properties
+Write-Info 'Configuring service properties...'
+
+& $NssmExe set $ServiceName DisplayName $DisplayName
+& $NssmExe set $ServiceName Description $Description
+& $NssmExe set $ServiceName AppDirectory $ServerDir
+& $NssmExe set $ServiceName Start SERVICE_DELAYED_AUTO_START
+& $NssmExe set $ServiceName AppStdout $StdoutLog
+& $NssmExe set $ServiceName AppStderr $StderrLog
+& $NssmExe set $ServiceName AppStdoutCreationDisposition 4   # append
+& $NssmExe set $ServiceName AppStderrCreationDisposition 4   # append
+& $NssmExe set $ServiceName AppRotateFiles 1
+& $NssmExe set $ServiceName AppRotateBytes 5242880           # 5 MB
+
+# Set environment: PORT=3131
+& $NssmExe set $ServiceName AppEnvironmentExtra 'PORT=3131'
+
+Write-Ok "Service '$ServiceName' installed successfully."
+
+# -- Post-install instructions ------------------------------------------------
+
+Write-Host ''
+Write-Host '+----------------------------------------------------------+' -ForegroundColor Green
+Write-Host '|  Agent Recon Windows Service Installed                   |' -ForegroundColor Green
+Write-Host '+----------------------------------------------------------+' -ForegroundColor Green
+Write-Host ''
+Write-Host '  Service Name:  AgentRecon' -ForegroundColor Cyan
+Write-Host "  Node.js:       $NodeExe"
+Write-Host "  Start Script:  $StartScript"
+Write-Host "  Working Dir:   $ServerDir"
+Write-Host "  Stdout Log:    $StdoutLog"
+Write-Host "  Stderr Log:    $StderrLog"
+Write-Host ''
+Write-Host '  Quick commands (run as Administrator):' -ForegroundColor Cyan
+Write-Host '    Start-Service AgentRecon              # Start the service'
+Write-Host '    Stop-Service AgentRecon               # Stop the service'
+Write-Host '    Restart-Service AgentRecon            # Restart'
+Write-Host '    Get-Service AgentRecon                # Check status'
+Write-Host '    .\install-service.ps1 -Status         # Detailed status'
+Write-Host '    .\install-service.ps1 -Uninstall      # Remove service'
+Write-Host ''
+Write-Host '  The service is set to start automatically (delayed) on boot.' -ForegroundColor Yellow
+Write-Host '  To start it now:  Start-Service AgentRecon' -ForegroundColor Yellow
+Write-Host ''
+Write-Host '  Dashboard: http://localhost:3131' -ForegroundColor Cyan
+Write-Host ''

package/installer/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Agent Recon™ Commercial License — see LICENSE-COMMERCIAL.
+'use strict';
+
+/**
+ * Agent Recon Installer — CLI Entry Point
+ *
+ * Usage:
+ *   node cli.js                  # guided install (default)
+ *   node cli.js install          # guided install
+ *   node cli.js install --tls    # guided install with mkcert TLS pre-selected
+ *   node cli.js upgrade          # upgrade existing installation
+ *   node cli.js upgrade --tls    # add mkcert TLS to existing install
+ *   node cli.js uninstall        # remove Agent Recon
+ *   node cli.js detect           # print environment report and exit
+ *   node cli.js tls setup        # standalone mkcert TLS setup (server must be running)
+ *   node cli.js tls status       # print current TLS status (server must be running)
+ *   node cli.js --help | -h      # print usage
+ *   node cli.js --version | -v   # print version
+ */
+
+const path = require('path');
+const ui   = require('./ui');
+
+// Read version from root package.json (the canonical version source)
+function getVersion() {
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    return pkg.version || '1.0.0';
+  } catch {
+    return '1.0.0';
+  }
+}
+
+function printUsage() {
+  const version = getVersion();
+  console.log(`
+${ui.bold('Agent Recon')}${ui.cyan('™')} Installer v${version}
+
+${ui.bold('Usage:')}
+  node cli.js [command]
+
+${ui.bold('Commands:')}
+  install     Guided installation (default)
+  upgrade     Upgrade an existing installation
+  uninstall   Remove Agent Recon™
+  detect      Print environment detection report
+  tls setup   Configure mkcert TLS (server must be running)
+  tls status  Show current TLS status (server must be running)
+
+${ui.bold('Options:')}
+  --help, -h       Show this help message
+  --version, -v    Show version number
+  --force          Force operation (skip version check on upgrade)
+  --tls            Pre-select mkcert TLS during install/upgrade
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'install';
+  const force = args.includes('--force');
+  const tlsFlag = args.includes('--tls');
+
+  if (command === '--help' || command === '-h') {
+    printUsage();
+    return;
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(getVersion());
+    return;
+  }
+
+  // Run environment detection (needed by all commands)
+  const { detectEnv } = require('./detect');
+  const envReport = await detectEnv();
+
+  switch (command) {
+    case 'detect': {
+      ui.banner(getVersion());
+      ui.printEnvReport(envReport);
+      return;
+    }
+
+    case 'install': {
+      // If existing install detected, suggest upgrade instead
+      if (envReport.existingInstall && envReport.existingInstall.manifestPath) {
+        ui.warn('An existing Agent Recon™ installation was detected.');
+        ui.info(`Version: ${envReport.existingInstall.version || 'unknown'}`);
+        ui.info(`Location: ${envReport.existingInstall.installDir || 'unknown'}`);
+        ui.info('Run "node cli.js upgrade" to upgrade, or "node cli.js install --force" to reinstall.');
+        if (!force) return;
+      }
+      const install = require('./install');
+      await install(envReport, { version: getVersion(), force, tls: tlsFlag });
+      return;
+    }
+
+    case 'upgrade': {
+      const upgrade = require('./upgrade');
+      await upgrade(envReport, { version: getVersion(), force, tls: tlsFlag });
+      return;
+    }
+
+    case 'tls': {
+      const sub = args[1];
+      if (sub === 'setup') {
+        await _tlsSetup();
+      } else if (sub === 'status') {
+        await _tlsStatus();
+      } else {
+        ui.error(`Unknown tls subcommand: ${sub || '(none)'}`);
+        ui.info('Usage: node cli.js tls setup | tls status');
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    case 'uninstall': {
+      const uninstall = require('./uninstall');
+      await uninstall(envReport);
+      return;
+    }
+
+    default:
+      ui.error(`Unknown command: ${command}`);
+      printUsage();
+      process.exitCode = 1;
+  }
+}
+
+async function _tlsSetup() {
+  ui.banner(getVersion());
+  ui.info('Configuring mkcert TLS via server API...');
+  try {
+    const r = await fetch('http://localhost:3131/api/settings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key: 'tls_enabled', value: 'true' }),
+    });
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    const r2 = await fetch('http://localhost:3131/api/settings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key: 'tls_mode', value: 'mkcert' }),
+    });
+    if (!r2.ok) throw new Error(`HTTP ${r2.status}`);
+    ui.ok('TLS enabled with mkcert mode. Restart the server to activate HTTPS.');
+    ui.info('If mkcert is not installed, install it and run: mkcert -install');
+  } catch (err) {
+    ui.error(`Could not reach server at localhost:3131: ${err.message}`);
+    ui.info('Make sure the Agent Recon™ server is running first.');
+  }
+}
+
+async function _tlsStatus() {
+  try {
+    const r = await fetch('http://localhost:3131/api/tls-status');
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    const data = await r.json();
+    console.log(`TLS status: ${data.status}`);
+    if (data.hint) console.log(`Hint: ${data.hint}`);
+    if (data.valid_to) console.log(`Valid until: ${data.valid_to}`);
+    if (data.days_remaining != null) console.log(`Days remaining: ${data.days_remaining}`);
+  } catch (err) {
+    ui.error(`Could not reach server at localhost:3131: ${err.message}`);
+    ui.info('Make sure the Agent Recon™ server is running first.');
+  }
+}
+
+main().catch(err => {
+  ui.error(err.message || String(err));
+  if (process.env.AGENT_RECON_DEBUG) console.error(err);
+  process.exitCode = 1;
+});