klio 1.4.1 → 1.4.3

package/README.md

@@ -2,6 +2,14 @@
 
 A command-line tool for astrological calculations, health analysis, and personalized astrology insights.
 
+**Features:**
+- Command-line interface for astrological calculations
+- Web-based GUI for easy exploration
+- Health data analysis from Apple Health exports
+- CSV data analysis with statistical testing
+- Personalized astrology with multiple chart support
+- AI integration for astrological insights
+
 ## Prerequisites
 
 ### For Linux Users
@@ -28,6 +36,26 @@ npm install -g klio
 klio [options]
 ```
 
+### Web Interface
+
+AstroCLI includes a web-based GUI that you can launch with the `--gui` flag:
+
+```bash
+klio --gui
+```
+
+This will start a web server on port 37421 (or a different port if specified) and open a browser interface where you can:
+
+- **Run commands** directly from the browser
+- **View command output** in a formatted display
+- **Browse all available commands** with examples and documentation
+- **Access command history** to reuse previous commands
+
+**Custom Port:**
+```bash
+klio --gui --gui-port 8080
+```
+
 ### Configuration
 
 - **Show status**: `--status` - Shows the stored configuration data
@@ -62,8 +90,6 @@ It's possible to analyze Apple Health data. This happens on the device and no se
 - **Step analysis**: `klio [planet] --apple <filepath> --steps` - Analyzes step patterns of any planet
 - **Stress analysis**: `klio [planet] --apple <filepath> --stress` - Analyzes stress patterns of planet sign stress based on HRV
 
-> Maybe I'll add some more in the future.
-
 ### CSV Analysis
 It's possible to analyze a csv with a column of either ISO date time or unix time stamp. 
 
@@ -72,9 +98,6 @@ It's possible to analyze a csv with a column of either ISO date time or unix tim
 
 The command also returns a Chi-Square. 
 
-You can research a lot of fun things with this. You find a lot of free datasets on Kaggle.
-
-
 ### Adding different charts
 
 - **Use personal data**: `--i` - Uses birth data from setup for calculations
@@ -99,6 +122,13 @@ Then, instead using `--i` for the commands from above you can use `--wp <id>` i.
 - **Past aspects**: `klio --v <count> [planet1] [aspect-type] [planet2]` - Shows past aspects (Format: --v <count> planet1 aspectType planet2) Available aspect types: c, o, s, t, se (conjunction, opposition, square, trine, sextile)
 - **Future aspects**: `klio --z <count> [planet1] [aspect-type] [planet2]` - Shows future aspects (Format: --z <count> planet1 aspectType planet2)
 
+### Planet Ingresses
+
+- **Planet ingress**: `klio [planet] --in [count]` - Shows when a planet enters a new zodiac sign. Optional count parameter for multiple ingresses (default: 1). Works with any planet (moon, mercury, venus, etc.)
+  - Example: `klio moon --in` - Shows next moon ingress
+  - Example: `klio saturn --in 2` - Shows next 2 Saturn ingresses (note: slow planets may have limited future data)
+  - Example: `klio mercury --in --d "15.03.2026"` - Shows next Mercury ingress from a specific date
+
 ### AI Integration
 
 - **AI model selection**: `--ai <model>` - Sets a specific AI model (e.g., "google/gemma-3n-e4b") for LM Studio ([lmstudio.ai](https://lmstudio.ai))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klio",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "A CLI for astrological calculations",
   "main": "src/main.js",
   "bin": {
@@ -23,8 +23,11 @@
     "commander": "^14.0.3",
     "csv": "^6.4.1",
     "csv-parser": "^3.0.0",
+    "express": "^4.19.2",
     "fast-xml-parser": "^5.3.4",
     "moment-timezone": "^0.6.0",
+    "node-fetch": "^3.3.2",
+    "sqlite3": "^5.1.7",
     "swisseph": "^0.5.17"
   }
 }

package/src/astrology/astrologyService.js

@@ -2491,6 +2491,223 @@ function analyzeHouseDistributionSignificance(houseDistribution) {
   };
 }
 
+// Function to calculate the next planet ingress (when planet enters a new sign)
+function calculateNextPlanetIngress(planetName, startDate = null, count = 1) {
+  // Use current date if no start date is provided
+  const startDateObj = startDate ? new Date(startDate.year, startDate.month - 1, startDate.day, startDate.hour, startDate.minute) : new Date();
+  
+  const results = [];
+  let currentDate = new Date(startDateObj);
+  
+  // Calculate timezone offset for the start date
+  const config = loadConfig();
+  let timezone = 'Europe/Zurich'; // Default
+  
+  if (config && config.currentLocation && config.currentLocation.timezone) {
+    timezone = config.currentLocation.timezone;
+  }
+  
+  const timezoneOffsetMinutes = getTimezoneOffset({
+    year: currentDate.getFullYear(),
+    month: currentDate.getMonth() + 1,
+    day: currentDate.getDate(),
+    hour: currentDate.getHours(),
+    minute: currentDate.getMinutes()
+  }, timezone);
+  
+  // Get current planet position
+  const currentPlanetData = getAstrologicalData(planetName, {
+    year: currentDate.getFullYear(),
+    month: currentDate.getMonth() + 1,
+    day: currentDate.getDate(),
+    hour: currentDate.getHours(),
+    minute: currentDate.getMinutes()
+  });
+  
+  let currentSignIndex = signs.indexOf(currentPlanetData.sign);
+  let targetSignIndex = (currentSignIndex + 1) % 12; // Next sign
+  
+  for (let i = 0; i < count; i++) {
+    // Find the next ingress by checking positions in 1-hour increments
+    let foundIngress = false;
+    let ingressDate = null;
+    let attempts = 0;
+    
+    // Dynamic search strategy based on planet speed
+    const verySlowPlanets = ['saturn', 'uranus', 'neptune', 'pluto'];
+    const mediumSlowPlanets = ['jupiter'];
+    const isVerySlowPlanet = verySlowPlanets.includes(planetName);
+    const isMediumSlowPlanet = mediumSlowPlanets.includes(planetName);
+    
+    // Determine time step based on planet speed
+    const timeStepHours = isVerySlowPlanet ? 24 : 
+                          isMediumSlowPlanet ? 6 : 
+                          1; // Daily for very slow, 6-hourly for medium, hourly for fast
+    
+    // Maximum search window (in days)
+    // For very slow planets, we need to search much further ahead
+    // Saturn: ~2.5 years per sign, so for multiple ingresses we need ~5-10 years
+    // Jupiter: ~1 year per sign, so for multiple ingresses we need ~3-5 years
+    // Uranus: ~7 years per sign, so we need ~15-20 years
+    // Neptune: ~13.75 years per sign, so we need ~25-30 years
+    // Pluto: ~20.7 years per sign, so we need ~35-40 years
+    // For fast planets (Moon, Mercury, Venus, Mars, Sun), we need a reasonable window per ingress
+    const fastPlanets = ['moon', 'mercury', 'venus', 'mars', 'sun'];
+    const isFastPlanet = fastPlanets.includes(planetName);
+    
+    const maxDays = isVerySlowPlanet ? 365 * 90 :
+                    isMediumSlowPlanet ? 365 * 90 :
+                    isFastPlanet ? 90 :  // 30 days for fast planets (enough for multiple moon ingresses)
+                    365 * 90; // Default for other planets
+    const maxAttempts = maxDays * 24 / timeStepHours;
+    
+    while (!foundIngress && attempts < maxAttempts) {
+      attempts++;
+      currentDate.setHours(currentDate.getHours() + timeStepHours);
+      
+      const testPlanetData = getAstrologicalData(planetName, {
+        year: currentDate.getFullYear(),
+        month: currentDate.getMonth() + 1,
+        day: currentDate.getDate(),
+        hour: currentDate.getHours(),
+        minute: currentDate.getMinutes()
+      });
+      
+      const testSignIndex = signs.indexOf(testPlanetData.sign);
+      
+      if (testSignIndex === targetSignIndex) {
+        // Found the ingress! Now refine to get more precise time
+        ingressDate = findExactPlanetIngressTime(planetName, currentDate, targetSignIndex, timezoneOffsetMinutes);
+        foundIngress = true;
+      }
+    }
+    
+    if (foundIngress) {
+      results.push({
+        sign: signs[targetSignIndex],
+        date: ingressDate,
+        fromSign: signs[currentSignIndex]
+      });
+      
+      // Prepare for next ingress
+      currentSignIndex = targetSignIndex;
+      targetSignIndex = (currentSignIndex + 1) % 12;
+      // Convert ingressDate object to Date object
+      currentDate = new Date(ingressDate.year, ingressDate.month - 1, ingressDate.day, ingressDate.hour, ingressDate.minute);
+      // For fast planets, start searching a few hours after the ingress to avoid missing the next one
+      if (isFastPlanet) {
+        currentDate.setHours(currentDate.getHours() + 6); // Start 6 hours after ingress
+      }
+    } else {
+      const daysLimit = isVerySlowPlanet ? 365 * 40 : 
+                       isMediumSlowPlanet ? 365 * 5 : 
+                       isFastPlanet ? 30 : 
+                       60;
+      console.log(`Could not find ${planetName} ingress to ${signs[targetSignIndex]} within ${daysLimit} days`);
+      if (isVerySlowPlanet) {
+        console.log(`💡 Note: For very slow planets like ${planetName}, the ephemeris data may not extend far enough into the future.`);
+      } else if (isMediumSlowPlanet) {
+        console.log(`💡 Note: For medium-slow planets like ${planetName}, the ephemeris data may not extend far enough into the future.`);
+      } else {
+        console.log(`💡 Note: For ${planetName}, the requested number of ingresses may be too high.`);
+      }
+      console.log(`💡 Try requesting fewer ingresses or use a shorter time frame with the --d option.`);
+      // Continue to next iteration instead of breaking the entire loop
+      continue;
+    }
+  }
+  
+  return results;
+}
+
+// Helper function to find exact planet ingress time using binary search
+function findExactPlanetIngressTime(planetName, approximateDate, targetSignIndex, timezoneOffsetMinutes) {
+  const targetLongitude = targetSignIndex * 30; // Each sign is 30 degrees
+  
+  // Convert approximate date to Julian Day
+  const approxJulianDay = calculateJulianDayUTC({
+    year: approximateDate.getFullYear(),
+    month: approximateDate.getMonth() + 1,
+    day: approximateDate.getDate(),
+    hour: approximateDate.getHours(),
+    minute: approximateDate.getMinutes()
+  }, timezoneOffsetMinutes);
+  
+  // Binary search parameters
+  let low = approxJulianDay - 0.1; // 2.4 hours before
+  let high = approxJulianDay + 0.1; // 2.4 hours after
+  let precision = 0.0001; // About 1.44 minutes precision
+  
+  // Perform binary search
+  for (let i = 0; i < 50; i++) {
+    const mid = (low + high) / 2;
+    const result = swisseph.swe_calc_ut(mid, planets[planetName], swisseph.SEFLG_SWIEPH | swisseph.SEFLG_SPEED);
+    
+    if (result.error) {
+      // Fallback to Moshier
+      const moshierResult = swisseph.swe_calc_ut(mid, planets[planetName], swisseph.SEFLG_MOSEPH | swisseph.SEFLG_SPEED);
+      if (moshierResult.error) {
+        console.error(`Error calculating ${planetName} position:`, moshierResult.error);
+        break;
+      }
+      result.longitude = moshierResult.longitude;
+    }
+    
+    if (result.longitude >= targetLongitude) {
+      high = mid;
+    } else {
+      low = mid;
+    }
+    
+    if (high - low < precision) {
+      break;
+    }
+  }
+  
+  // Convert Julian Day back to date components
+  const finalJulianDay = (low + high) / 2;
+  return convertJulianDayToDate(finalJulianDay, timezoneOffsetMinutes);
+}
+
+// Helper function to convert Julian Day to date components
+function convertJulianDayToDate(julianDay, timezoneOffsetMinutes) {
+  // This is a simplified conversion - for more accuracy, use a proper algorithm
+  // We'll use the Swiss Ephemeris function if available
+  try {
+    const result = swisseph.swe_revjul(julianDay, swisseph.SE_GREG_CAL);
+    
+    // Extract minutes from the decimal part of the hour
+    const hour = Math.floor(result.hour);
+    const minute = Math.round((result.hour - hour) * 60);
+    
+    // Adjust for timezone
+    const utcDate = new Date(Date.UTC(result.year, result.month - 1, result.day, hour, minute));
+    utcDate.setMinutes(utcDate.getMinutes() + timezoneOffsetMinutes);
+    
+    return {
+      year: utcDate.getFullYear(),
+      month: utcDate.getMonth() + 1,
+      day: utcDate.getDate(),
+      hour: utcDate.getHours(),
+      minute: utcDate.getMinutes()
+    };
+  } catch (error) {
+    console.error('Error converting Julian Day to date:', error);
+    
+    // Fallback: return approximate date
+    const baseDate = new Date();
+    baseDate.setTime((julianDay - 2440587.5) * 86400000); // Convert Julian Day to milliseconds
+    
+    return {
+      year: baseDate.getFullYear(),
+      month: baseDate.getMonth() + 1,
+      day: baseDate.getDate(),
+      hour: baseDate.getHours(),
+      minute: baseDate.getMinutes()
+    };
+  }
+}
+
 
 module.exports = {
   calculateHouses,
@@ -2527,5 +2744,6 @@ module.exports = {
   analyzeSignDistributionSignificance,
   calculateAspectStatistics,
   calculatePlanetComboAspects,
-  showPlanetComboAspects
+  showPlanetComboAspects,
+  calculateNextPlanetIngress
 };

package/src/cli/cli.js

@@ -1,7 +1,7 @@
 const { Command } = require('commander');
 const { planets, signs } = require('../astrology/astrologyConstants');
 const { showRetrogradePlanets } = require('../astrology/retrogradeService');
-const { getCurrentTimeInTimezone, showAspectFigures, analyzeElementDistribution, getTimezoneOffset, calculateJulianDayUTC, calculateHouses, getAstrologicalData, getPlanetHouse, showPlanetAspects, calculatePlanetAspects, getAllActiveAspects, showAllActiveAspects, getBirthDataFromConfig, getPersonDataFromConfig, detectAspectFigures, calculatePersonalTransits, showPersonalTransitAspects, showCombinedAnalysis, calculatePersonalTransitAspects, determineAspectPhase, findExactAspectTime, findLastExactAspectTime, getAspectAngle, getFutureAspects, getPastAspects, analyzeCSVWithDatetime, analyzeHouseDistributionSignificance, analyzeAspectDistributionSignificance, analyzeSignDistributionSignificance, calculateAspectStatistics, calculatePlanetComboAspects, showPlanetComboAspects, getCriticalPlanets, getHouseSystemCode } = require('../astrology/astrologyService');
+const { getCurrentTimeInTimezone, showAspectFigures, analyzeElementDistribution, getTimezoneOffset, calculateJulianDayUTC, calculateHouses, getAstrologicalData, getPlanetHouse, showPlanetAspects, calculatePlanetAspects, getAllActiveAspects, showAllActiveAspects, getBirthDataFromConfig, getPersonDataFromConfig, detectAspectFigures, calculatePersonalTransits, showPersonalTransitAspects, showCombinedAnalysis, calculatePersonalTransitAspects, determineAspectPhase, findExactAspectTime, findLastExactAspectTime, getAspectAngle, getFutureAspects, getPastAspects, analyzeCSVWithDatetime, analyzeHouseDistributionSignificance, analyzeAspectDistributionSignificance, analyzeSignDistributionSignificance, calculateAspectStatistics, calculatePlanetComboAspects, showPlanetComboAspects, getCriticalPlanets, getHouseSystemCode, calculateNextPlanetIngress } = require('../astrology/astrologyService');
 const { performSetup, showConfigStatus, loadConfig, setAIModel, askAIModel, setPerson1, setPerson2, setPerson, getPersonData, listPeople, deletePerson } = require('../config/configService');
 const { parseAppleHealthXML } = require('../health/healthService');
 const { analyzeStepsByPlanetSign, analyzeStressByPlanetAspects, analyzePlanetAspectsForSleep } = require('../health/healthAnalysis');
@@ -11,6 +11,15 @@ const swisseph = require('swisseph');
 const path = require('path');
 const fs = require('fs');
 
+// GUI Server import
+let guiServer = null;
+try {
+  guiServer = require('../gui/server');
+} catch (error) {
+  // GUI server not available (optional feature)
+  console.debug('GUI server not available');
+}
+
 const program = new Command();
 
 // Helper function to check if person data should be used (including new options)
@@ -245,11 +254,40 @@ program
   .option('--v <count>', 'Shows past aspects between two planets (Format: --v <count> planet1 aspectType planet2)')
   .option('--z <count>', 'Shows future aspects between two planets (Format: --z <count> planet1 aspectType planet2)')
   .option('--csv <filepath>', 'Analyzes a CSV file with ISO-Datetime values or Unix timestamps')
+  .option('--in [count]', 'Shows next planet ingress (entering new sign). Optional count for multiple ingresses')
+  .option('--gui', 'Launches the web interface for command history (port 37421)')
+  .option('--gui-port <port>', 'Specify custom port for GUI server')
   .description('Shows astrological data for a planet')
   .action(async (planetArg, planet2Arg, options) => {
     // If planet2Arg is an object, it contains the options (commander behavior)
     let planet2 = typeof planet2Arg === 'string' ? planet2Arg : null;
     let actualOptions = typeof planet2Arg === 'object' ? planet2Arg : options;
+
+    // Handle GUI launch if --gui flag is specified
+    if (options.gui) {
+      if (!guiServer) {
+        console.error('❌ GUI server is not available. Please install required dependencies.');
+        console.error('💡 Run: npm install express sqlite3');
+        process.exit(1);
+      }
+
+      try {
+        await guiServer.initialize();
+        const port = options.guiPort ? parseInt(options.guiPort) : 37421;
+        await guiServer.start(port);
+        
+        console.log(`\n🌐 GUI Server started successfully!`);
+        console.log(`📊 Open your browser and navigate to: http://localhost:${guiServer.getPort()}`);
+        console.log(`💡 Press Ctrl+C to stop the server and return to CLI`);
+        
+        // Keep the process running
+        await new Promise(() => {});
+        return;
+      } catch (err) {
+        console.error('❌ Failed to start GUI server:', err.message);
+        process.exit(1);
+      }
+    }
     
     // Show critical planets if --c option is specified (no planet required)
     if (actualOptions.c) {
@@ -975,6 +1013,105 @@ program
       return;
     }
 
+    // Show next planet ingress if --in option is specified
+    if (options.in) {
+      // Determine the planet to use (default to moon if no planet specified)
+      const planetName = planetArg ? planetArg.toLowerCase() : 'moon';
+      
+      // Validate planet name
+      if (planets[planetName] === undefined) {
+        console.error(`Error: Invalid planet '${planetName}'. Available planets: ${Object.keys(planets).join(', ')}`);
+        process.exit(1);
+      }
+      
+      // Parse the count parameter (default to 1 if not specified)
+      const count = options.in && typeof options.in === 'string' && options.in.trim() ? parseInt(options.in) : 1;
+      
+      // Use custom date if specified
+      let customDate = null;
+      if (options.d) {
+        // Try to parse the date as DD.MM.YYYY or DD.MM.YYYY HH:MM
+        const dateRegex = /^(\d{1,2})\.(\d{1,2})\.(\d{4})(?:\s+(\d{1,2}):(\d{2}))?$/;
+        const match = options.d.match(dateRegex);
+        
+        if (match) {
+          const day = parseInt(match[1], 10);
+          const month = parseInt(match[2], 10);
+          const year = parseInt(match[3], 10);
+          const hour = match[4] ? parseInt(match[4], 10) : 12; // Default: 12 o'clock
+          const minute = match[5] ? parseInt(match[5], 10) : 0; // Default: 0 minutes
+          
+          // Check if the date is valid
+          const date = new Date(year, month - 1, day, hour, minute);
+          if (date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day) {
+            customDate = {
+              day: day,
+              month: month,
+              year: year,
+              hour: hour,
+              minute: minute
+            };
+            console.log(`Using custom date: ${day}.${month}.${year} ${hour}:${minute.toString().padStart(2, '0')}`);
+          } else {
+            console.error('Invalid date:', options.d);
+            console.error('💡 Please use the format: DD.MM.YYYY or "DD.MM.YYYY HH:MM" (with quotes for date with time)');
+            process.exit(1);
+          }
+        } else {
+          console.error('Invalid date:', options.d);
+          console.error('💡 Please use the format: DD.MM.YYYY or "DD.MM.YYYY HH:MM" (with quotes for date with time)');
+          process.exit(1);
+        }
+      }
+      
+      // Calculate next planet ingress(es)
+      const ingresses = calculateNextPlanetIngress(planetName, customDate, count);
+      
+      if (ingresses.length === 0) {
+        console.log(`No ${planetName} ingresses found.`);
+        return;
+      }
+      
+      const planetNameCapitalized = planetName.charAt(0).toUpperCase() + planetName.slice(1);
+      console.log(`Next ${planetNameCapitalized} Ingress(es):`);
+      console.log('================================================================================');
+      console.log('| #   | Date & Time           | From Sign    | To Sign      |');
+      console.log('================================================================================');
+      
+      ingresses.forEach((ingress, index) => {
+        const dateStr = `${ingress.date.day.toString().padStart(2, '0')}.${ingress.date.month.toString().padStart(2, '0')}.${ingress.date.year} ${ingress.date.hour.toString().padStart(2, '0')}:${ingress.date.minute.toString().padStart(2, '0')}`;
+        const fromSign = ingress.fromSign.padEnd(12, ' ');
+        const toSign = ingress.sign.padEnd(12, ' ');
+        
+        console.log(`| ${(index + 1).toString().padEnd(2)} | ${dateStr.padEnd(21)} | ${fromSign} | ${toSign} |`);
+      });
+      
+      console.log('================================================================================');
+      
+      if (count > 1) {
+        console.log(`\nShowing ${ingresses.length} ${planetName} ingresses starting from ${customDate ? 'the specified date' : 'now'}.`);
+      } else {
+        console.log(`\nShowing the next ${planetName} ingress from ${customDate ? 'the specified date' : 'now'}.`);
+      }
+      
+      // Handle AI request
+      if (options.p) {
+        const aiData = {
+          planet: planetName,
+          sign: 'Multiple',
+          degreeInSign: 'Multiple',
+          dignity: `Next ${planetName} ingress: ${ingresses[0].sign} at ${ingresses[0].date.day}.${ingresses[0].date.month}.${ingresses[0].date.year} ${ingresses[0].date.hour}:${ingresses[0].date.minute.toString().padStart(2, '0')}`,
+          element: 'Multiple',
+          decan: 'Multiple',
+          planetIngresses: ingresses
+        };
+        
+        await handleAIRequest(options, aiData);
+      }
+      
+      return;
+    }
+
     // For other options, a planet is required (except for --a or --s without planet)
     if (!planetArg && !options.a && !options.s) {
       console.error('Error: Planet is required for this operation.');

package/src/gui/commandLogger.js

@@ -0,0 +1,67 @@
+const commandDatabase = require('./database');
+
+class CommandLogger {
+  constructor() {
+    this.isInitialized = false;
+  }
+
+  async initialize() {
+    try {
+      await commandDatabase.initialize();
+      this.isInitialized = true;
+    } catch (err) {
+      console.error('Failed to initialize command logger:', err);
+      this.isInitialized = false;
+    }
+  }
+
+  async logCommand(command, arguments = '', category = 'general', tags = '') {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (!this.isInitialized) {
+      return false;
+    }
+
+    try {
+      // Capture the command result by temporarily overriding console.log
+      const originalLog = console.log;
+      let capturedOutput = '';
+
+      console.log = (...args) => {
+        capturedOutput += args.join(' ') + '\n';
+        originalLog(...args);
+      };
+
+      // Execute the command (this would be called from CLI)
+      // For now, we'll just save the command structure
+      
+      const commandId = await commandDatabase.saveCommand(
+        command,
+        arguments,
+        '', // Result will be captured later
+        tags,
+        category
+      );
+
+      // Restore original console.log
+      console.log = originalLog;
+
+      return commandId;
+    } catch (err) {
+      console.error('Error logging command:', err);
+      return false;
+    }
+  }
+
+  async close() {
+    try {
+      await commandDatabase.close();
+    } catch (err) {
+      console.error('Error closing command logger:', err);
+    }
+  }
+}
+
+module.exports = new CommandLogger();

package/src/gui/database.js

@@ -0,0 +1,135 @@
+const sqlite3 = require('sqlite3').verbose();
+const path = require('path');
+const fs = require('fs');
+
+class CommandDatabase {
+  constructor() {
+    this.dbPath = path.join(__dirname, '..', '..', 'commands.db');
+    this.db = null;
+  }
+
+  async initialize() {
+    // Create directory if it doesn't exist
+    const dbDir = path.dirname(this.dbPath);
+    if (!fs.existsSync(dbDir)) {
+      fs.mkdirSync(dbDir, { recursive: true });
+    }
+
+    this.db = new sqlite3.Database(this.dbPath);
+
+    return new Promise((resolve, reject) => {
+      this.db.serialize(() => {
+        this.db.run(`
+          CREATE TABLE IF NOT EXISTS commands (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+            command TEXT NOT NULL,
+            arguments TEXT,
+            result TEXT,
+            tags TEXT,
+            category TEXT
+          )
+        `);
+
+        // Create indexes for better search performance
+        this.db.run('CREATE INDEX IF NOT EXISTS idx_command ON commands(command)');
+        this.db.run('CREATE INDEX IF NOT EXISTS idx_timestamp ON commands(timestamp)');
+        this.db.run('CREATE INDEX IF NOT EXISTS idx_tags ON commands(tags)');
+        this.db.run('CREATE INDEX IF NOT EXISTS idx_category ON commands(category)');
+      });
+
+      resolve();
+    });
+  }
+
+  async saveCommand(command, args = '', result = '', tags = '', category = '') {
+    return new Promise((resolve, reject) => {
+      const stmt = this.db.prepare(
+        'INSERT INTO commands (command, arguments, result, tags, category) VALUES (?, ?, ?, ?, ?)'
+      );
+      stmt.run([command, args, result, tags, category], function(err) {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(this.lastID);
+        }
+      });
+      stmt.finalize();
+    });
+  }
+
+  async getAllCommands() {
+    return new Promise((resolve, reject) => {
+      this.db.all('SELECT * FROM commands ORDER BY timestamp DESC', (err, rows) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(rows);
+        }
+      });
+    });
+  }
+
+  async searchCommands(query) {
+    return new Promise((resolve, reject) => {
+      const searchQuery = `%${query}%`;
+      this.db.all(`
+        SELECT * FROM commands 
+        WHERE command LIKE ? 
+        OR arguments LIKE ? 
+        OR result LIKE ? 
+        OR tags LIKE ? 
+        OR category LIKE ?
+        ORDER BY timestamp DESC
+      `, [searchQuery, searchQuery, searchQuery, searchQuery, searchQuery], (err, rows) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(rows);
+        }
+      });
+    });
+  }
+
+  async getCommandById(id) {
+    return new Promise((resolve, reject) => {
+      this.db.get('SELECT * FROM commands WHERE id = ?', [id], (err, row) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(row);
+        }
+      });
+    });
+  }
+
+  async getCommandsByCategory(category) {
+    return new Promise((resolve, reject) => {
+      this.db.all('SELECT * FROM commands WHERE category = ? ORDER BY timestamp DESC', [category], (err, rows) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(rows);
+        }
+      });
+    });
+  }
+
+  async close() {
+    return new Promise((resolve, reject) => {
+      if (this.db) {
+        this.db.close((err) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve();
+          }
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+}
+
+module.exports = new CommandDatabase();

package/src/gui/public/index.html

@@ -0,0 +1,381 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Klio GUI</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }
+        .command-input {
+            font-family: 'Courier New', monospace;
+        }
+        .output-area {
+            font-family: 'Courier New', monospace;
+            white-space: pre-wrap;
+        }
+        .nav-link {
+            transition: all 0.2s ease;
+        }
+        .nav-link:hover {
+            background-color: rgba(59, 130, 246, 0.1);
+        }
+        .nav-link.active {
+            background-color: rgba(59, 130, 246, 0.2);
+            border-left: 3px solid #3b82f6;
+        }
+    </style>
+</head>
+<body class="bg-gray-50 min-h-screen">
+    <div class="flex min-h-screen">
+        <!-- Sidebar Navigation -->
+        <div class="w-64 bg-white border-r border-gray-200 flex flex-col">
+            <div class="p-4 border-b border-gray-200">
+                <h1 class="text-xl font-bold text-gray-800">Klio GUI</h1>
+                <p class="text-sm text-gray-600">Web Interface</p>
+            </div>
+            
+            <nav class="flex-1 p-4">
+                <ul class="space-y-2">
+                    <li>
+                        <a href="#" onclick="showPage('runner')" id="nav-runner" class="nav-link flex items-center p-3 rounded-lg text-gray-700 active">
+                            <svg class="w-5 h-5 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z"></path>
+                            </svg>
+                            Command Runner
+                        </a>
+                    </li>
+                    <li>
+                        <a href="#" onclick="showPage('commands')" id="nav-commands" class="nav-link flex items-center p-3 rounded-lg text-gray-700">
+                            <svg class="w-5 h-5 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"></path>
+                            </svg>
+                            Commands Reference
+                        </a>
+                    </li>
+                    <li>
+                        <a href="#" onclick="showPage('history')" id="nav-history" class="nav-link flex items-center p-3 rounded-lg text-gray-700">
+                            <svg class="w-5 h-5 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"></path>
+                            </svg>
+                            Command History
+                        </a>
+                    </li>
+                </ul>
+            </nav>
+            
+            <div class="p-4 border-t border-gray-200">
+                <div class="text-xs text-gray-500">
+                    <p>Klio GUI v0.1</p>
+                    <p>GUI Interface</p>
+                </div>
+            </div>
+        </div>
+        
+        <!-- Main Content -->
+        <div class="flex-1 flex flex-col">
+            <!-- Header -->
+            <header class="bg-white border-b border-gray-200 p-4">
+                <div class="flex items-center justify-between">
+                    <h1 class="text-lg font-semibold text-gray-800" id="page-title">Command Runner</h1>
+                </div>
+            </header>
+            
+            <!-- Page Content -->
+            <main class="flex-1 overflow-y-auto p-6">
+                <!-- Command Runner Page -->
+                <div id="runner-page">
+                    <div class="bg-white shadow-sm rounded-lg p-6 mb-6">
+                        <div class="mb-4">
+                            <label for="commandInput" class="block text-sm font-medium text-gray-700 mb-2">Command</label>
+                            <div class="flex gap-2">
+                                <input 
+                                    type="text" 
+                                    id="commandInput" 
+                                    placeholder="e.g., moon --s"
+                                    class="flex-1 command-input px-4 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                                >
+                                <button 
+                                    onclick="runCommand()"
+                                    class="px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
+                                >
+                                    Run
+                                </button>
+                            </div>
+                        </div>
+                        <div class="text-sm text-gray-600">
+                            <p class="mb-2">Examples:</p>
+                            <div class="flex flex-wrap gap-4 text-xs">
+                                <button onclick="commandInput.value = '--v 3 saturn neptune'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">moon --s</button>
+                                <button onclick="commandInput.value = '--rx --i'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">--rx</button>
+                                <button onclick="commandInput.value = '--c'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">--c</button>
+                                <button onclick="commandInput.value = 'mars venus --k'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">mars venus --k</button>
+                                <button onclick="commandInput.value = '--el'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">--el</button>
+                                <button onclick="commandInput.value = '--s'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">--el</button>
+                                <button onclick="commandInput.value = '--a'; commandInput.focus()" class="px-3 py-1 bg-gray-100 rounded hover:bg-gray-200">--el</button>
+
+
+                            </div>
+                        </div>
+                    </div>
+
+                    <div class="bg-white shadow-sm rounded-lg p-6">
+                        <h2 class="text-lg font-semibold text-gray-800 mb-4">Output</h2>
+                        <div id="outputArea" class="output-area bg-gray-100 p-4 rounded border min-h-[300px]">
+                            Command output will appear here...
+                        </div>
+                    </div>
+                </div>
+                
+                <!-- Commands Reference Page -->
+                <div id="commands-page" class="hidden">
+                    <div class="bg-white shadow-sm rounded-lg p-6">
+                        <h2 class="text-lg font-semibold text-gray-800 mb-4">Available Commands</h2>
+                        <div class="prose max-w-none text-sm">
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">Basic Astrological Data</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio [planet]</code> - Displays astrological data for a specific planet</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio [planet] --hs koch</code> - Shows planet data with house and house system</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio [planet] [planet2] --k</code> - Shows aspects between two planets</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio --a</code> - Shows all current aspects</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio --s</code> - Shows all planet positions</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">klio --s --hs placidus</code> - Different house systems</li>
+                            </ul>
+                            
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">House Systems</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--hs &lt;system&gt;</code> - Shows planet + house position (Placidus, Koch, Porphyry, Regiomontanus, Campanus, Equal, WholeSign, Gauquelin, Vehlow, Topocentric, Alcabitius, Morinus)</li>
+                            </ul>
+                            
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">Date and Time</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--d &lt;date&gt;</code> - Use a specific date (Format: DD.MM.YYYY or "DD.MM.YYYY HH:MM")</li>
+                            </ul>
+                            
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">Advanced Features</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--rx</code> - Shows all retrograde or stationary planets</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--c</code> - Shows all planets on critical degrees</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--el</code> - Shows element distribution of planets</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--af</code> - Shows active aspect figures</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--tr</code> - Shows personal transits based on birth data</li>
+                            </ul>
+                            
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">Past and Future Aspects</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--v &lt;count&gt; [planet1] [aspect-type] [planet2]</code> - Shows past aspects</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--z &lt;count&gt; [planet1] [aspect-type] [planet2]</code> - Shows future aspects</li>
+                            </ul>
+                            
+                            <h3 class="text-base font-semibold text-gray-800 mt-6 mb-3">Configuration</h3>
+                            <ul class="list-disc pl-6 space-y-2">
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--setup</code> - Setup for a default chart</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--status</code> - Shows the stored configuration data</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--i</code> - Uses birth data from setup</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--person &lt;id&gt; &lt;data&gt;</code> - Creates or updates any person</li>
+                                <li><code class="bg-gray-100 px-2 py-1 rounded">--people</code> - Lists all saved persons</li>
+                            </ul>
+                        </div>
+                    </div>
+                </div>
+                
+                <!-- Command History Page -->
+                <div id="history-page" class="hidden">
+                    <div class="bg-white shadow-sm rounded-lg p-6">
+                        <h2 class="text-lg font-semibold text-gray-800 mb-4">Command History</h2>
+                        <div id="historyContainer" class="space-y-2 max-h-[500px] overflow-y-auto pr-2"></div>
+                    </div>
+                </div>
+            </main>
+        </div>
+    </div>
+
+    <div id="toast" class="fixed bottom-4 right-4 bg-gray-800 text-white px-4 py-2 rounded-md shadow-lg opacity-0 transform translate-y-4 transition-all duration-300"></div>
+
+    <script>
+        let commandHistory = [];
+        const maxHistory = 50;
+
+        // DOM elements
+        const commandInput = document.getElementById('commandInput');
+        const historyContainer = document.getElementById('historyContainer');
+        const outputArea = document.getElementById('outputArea');
+        const toastElement = document.getElementById('toast');
+
+        // Initialize the app
+        function init() {
+            loadHistory();
+            
+            // Add event listener for Enter key
+            commandInput.addEventListener('keypress', (e) => {
+                if (e.key === 'Enter') {
+                    runCommand();
+                }
+            });
+            
+            // Focus on command input
+            commandInput.focus();
+        }
+
+        // Page navigation function
+        function showPage(pageName) {
+            // Hide all pages
+            document.getElementById('runner-page').classList.add('hidden');
+            document.getElementById('commands-page').classList.add('hidden');
+            document.getElementById('history-page').classList.add('hidden');
+            
+            // Remove active state from all nav items
+            document.getElementById('nav-runner').classList.remove('active');
+            document.getElementById('nav-commands').classList.remove('active');
+            document.getElementById('nav-history').classList.remove('active');
+            
+            // Show selected page
+            if (pageName === 'runner') {
+                document.getElementById('runner-page').classList.remove('hidden');
+                document.getElementById('nav-runner').classList.add('active');
+                document.getElementById('page-title').textContent = 'Command Runner';
+            } else if (pageName === 'commands') {
+                document.getElementById('commands-page').classList.remove('hidden');
+                document.getElementById('nav-commands').classList.add('active');
+                document.getElementById('page-title').textContent = 'Commands Reference';
+            } else if (pageName === 'history') {
+                document.getElementById('history-page').classList.remove('hidden');
+                document.getElementById('nav-history').classList.add('active');
+                document.getElementById('page-title').textContent = 'Command History';
+            }
+        }
+
+        // Load history from localStorage
+        function loadHistory() {
+            try {
+                const savedHistory = localStorage.getItem('astrocliHistory');
+                if (savedHistory) {
+                    commandHistory = JSON.parse(savedHistory);
+                    renderHistory();
+                }
+            } catch (error) {
+                console.error('Error loading history:', error);
+            }
+        }
+
+        // Save history to localStorage
+        function saveHistory() {
+            try {
+                localStorage.setItem('astrocliHistory', JSON.stringify(commandHistory));
+            } catch (error) {
+                console.error('Error saving history:', error);
+            }
+        }
+
+        // Add command to history
+        function addToHistory(command) {
+            // Remove duplicate if exists
+            commandHistory = commandHistory.filter(cmd => cmd !== command);
+            
+            // Add new command to beginning
+            commandHistory.unshift(command);
+            
+            // Limit history size
+            if (commandHistory.length > maxHistory) {
+                commandHistory = commandHistory.slice(0, maxHistory);
+            }
+            
+            saveHistory();
+            renderHistory();
+        }
+
+        // Render history
+        function renderHistory() {
+            if (commandHistory.length === 0) {
+                historyContainer.innerHTML = '<div class="text-gray-500 text-sm">No command history yet</div>';
+                return;
+            }
+            
+            let html = '<div class="space-y-1">';
+            commandHistory.forEach((cmd, index) => {
+                html += `<div 
+                    class="command-input px-3 py-2 bg-gray-100 rounded cursor-pointer hover:bg-gray-200 text-sm truncate"
+                    title="${cmd}"
+                    onclick="commandInput.value = '${cmd.replace(/'/g, "\\'")}'; showPage('runner'); commandInput.focus()"
+                >${cmd}</div>`;
+            });
+            html += '</div>';
+            
+            historyContainer.innerHTML = html;
+        }
+
+        // Run command
+        async function runCommand() {
+            const command = commandInput.value.trim();
+            
+            if (!command) {
+                showToast('Please enter a command');
+                return;
+            }
+            
+            try {
+                // Show loading state
+                outputArea.textContent = 'Running command...\n\n';
+                
+                // Add to history
+                addToHistory(command);
+                
+                // Clear input for next command
+                commandInput.value = '';
+                
+                // Run the command via API
+                const response = await fetch('/api/run-command', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({ command })
+                });
+                
+                const result = await response.json();
+                
+                if (response.ok) {
+                    // Display the result with better formatting
+                    if (result.output) {
+                        const cleanedOutput = result.output
+                            .replace(/\n{3,}/g, '\n\n')
+                            .trim();
+                        outputArea.textContent = cleanedOutput;
+                    } else {
+                        outputArea.textContent = 'Command executed successfully';
+                    }
+                } else {
+                    let errorMessage = 'Error: ' + result.error;
+                    if (result.details) {
+                        errorMessage += '\n' + result.details;
+                    }
+                    outputArea.textContent = errorMessage;
+                    showToast('Command failed');
+                }
+                
+            } catch (error) {
+                console.error('Error running command:', error);
+                outputArea.textContent = 'Error: ' + error.message;
+                showToast('Command failed');
+            }
+        }
+
+        // Show toast message
+        function showToast(message) {
+            toastElement.textContent = message;
+            toastElement.classList.remove('opacity-0', 'translate-y-4');
+            toastElement.classList.add('opacity-100', 'translate-y-0');
+            
+            setTimeout(() => {
+                toastElement.classList.add('opacity-0', 'translate-y-4');
+                toastElement.classList.remove('opacity-100', 'translate-y-0');
+            }, 3000);
+        }
+
+        // Initialize the app when DOM is loaded
+        document.addEventListener('DOMContentLoaded', init);
+    </script>
+</body>
+</html>

package/src/gui/routes/api.js

@@ -0,0 +1,134 @@
+const express = require('express');
+const router = express.Router();
+const commandDatabase = require('../database');
+const { exec } = require('child_process');
+const path = require('path');
+
+// Initialize database
+commandDatabase.initialize().catch(err => {
+  console.error('Failed to initialize database:', err);
+});
+
+// Get all commands
+router.get('/commands', async (req, res) => {
+  try {
+    const commands = await commandDatabase.getAllCommands();
+    res.json(commands);
+  } catch (err) {
+    console.error('Error fetching commands:', err);
+    res.status(500).json({ error: 'Failed to fetch commands' });
+  }
+});
+
+// Search commands
+router.get('/commands/search', async (req, res) => {
+  const query = req.query.q || '';
+  
+  try {
+    const results = await commandDatabase.searchCommands(query);
+    res.json(results);
+  } catch (err) {
+    console.error('Error searching commands:', err);
+    res.status(500).json({ error: 'Failed to search commands' });
+  }
+});
+
+// Get specific command by ID
+router.get('/commands/:id', async (req, res) => {
+  try {
+    const command = await commandDatabase.getCommandById(req.params.id);
+    if (command) {
+      res.json(command);
+    } else {
+      res.status(404).json({ error: 'Command not found' });
+    }
+  } catch (err) {
+    console.error('Error fetching command:', err);
+    res.status(500).json({ error: 'Failed to fetch command' });
+  }
+});
+
+// Get commands by category
+router.get('/commands/category/:category', async (req, res) => {
+  try {
+    const commands = await commandDatabase.getCommandsByCategory(req.params.category);
+    res.json(commands);
+  } catch (err) {
+    console.error('Error fetching commands by category:', err);
+    res.status(500).json({ error: 'Failed to fetch commands by category' });
+  }
+});
+
+// Save a new command
+router.post('/commands', async (req, res) => {
+  try {
+    const { command, args, result, tags, category } = req.body;
+    
+    if (!command) {
+      return res.status(400).json({ error: 'Command is required' });
+    }
+    
+    const commandId = await commandDatabase.saveCommand(command, args, result, tags, category);
+    res.status(201).json({ id: commandId, message: 'Command saved successfully' });
+  } catch (err) {
+    console.error('Error saving command:', err);
+    res.status(500).json({ error: 'Failed to save command' });
+  }
+});
+
+// Health check endpoint
+router.get('/health', (req, res) => {
+  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
+});
+
+// Run command endpoint
+router.post('/run-command', async (req, res) => {
+  try {
+    const { command } = req.body;
+    
+    if (!command) {
+      return res.status(400).json({ error: 'Command is required' });
+    }
+    
+    // Execute the command using child_process
+    const commandToRun = command.startsWith('klio ') ? command : `klio ${command}`;
+    const mainJsPath = path.join(__dirname, '..', '..', '..', 'src', 'main.js');
+    
+    exec(`node ${mainJsPath} ${command}`, { 
+      cwd: path.join(__dirname, '..', '..', '..'),
+      maxBuffer: 1024 * 1024 * 10 // 10MB buffer
+    }, (error, stdout, stderr) => {
+      if (error) {
+        console.error('Command execution error:', error);
+        console.error('Stderr:', stderr);
+        return res.status(500).json({
+          error: 'Command execution failed',
+          details: stderr || error.message,
+          command: commandToRun
+        });
+      }
+      
+      // Save command to history
+      commandDatabase.saveCommand(
+        command,
+        '',
+        stdout,
+        '',
+        'executed'
+      ).catch(err => {
+        console.error('Failed to save command to history:', err);
+      });
+      
+      res.json({
+        output: stdout,
+        command: command
+      });
+    });
+    
+  } catch (err) {
+    console.error('Error in run-command endpoint:', err);
+    res.status(500).json({ error: 'Failed to execute command' });
+  }
+});
+
+module.exports = router;

package/src/gui/server.js

@@ -0,0 +1,82 @@
+const express = require('express');
+const path = require('path');
+const apiRouter = require('./routes/api');
+const commandDatabase = require('./database');
+
+class GUIServer {
+  constructor() {
+    this.app = express();
+    this.server = null;
+    this.port = 37421; // Less common port
+  }
+
+  async initialize() {
+    // Initialize database
+    await commandDatabase.initialize();
+
+    // Middleware
+    this.app.use(express.json());
+    this.app.use(express.urlencoded({ extended: true }));
+
+    // API routes
+    this.app.use('/api', apiRouter);
+
+    // Serve static files from public directory
+    this.app.use(express.static(path.join(__dirname, 'public')));
+
+    // Serve index.html for all other routes (for SPA behavior)
+    this.app.get('*', (req, res) => {
+      res.sendFile(path.join(__dirname, 'public', 'index.html'));
+    });
+
+    // Error handling middleware
+    this.app.use((err, req, res, next) => {
+      console.error('Server error:', err);
+      res.status(500).json({ error: 'Internal server error' });
+    });
+  }
+
+  start(port = this.port) {
+    return new Promise((resolve, reject) => {
+      this.server = this.app.listen(port, () => {
+        console.log(`🌐 GUI Server running on http://localhost:${port}`);
+        console.log(`📊 Command history available at http://localhost:${port}`);
+        console.log('💡 Press Ctrl+C to stop the server');
+        resolve();
+      });
+
+      this.server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          console.error(`Port ${port} is already in use. Trying port ${port + 1}...`);
+          this.start(port + 1).then(resolve).catch(reject);
+        } else {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  async stop() {
+    return new Promise((resolve, reject) => {
+      if (this.server) {
+        this.server.close(async () => {
+          await commandDatabase.close();
+          console.log('GUI Server stopped');
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  getPort() {
+    if (this.server) {
+      const address = this.server.address();
+      return address && address.port;
+    }
+    return this.port;
+  }
+}
+
+module.exports = new GUIServer();