ether-to-astro 1.2.0 → 1.3.0

package/src/astro-service/electional-service.ts

@@ -0,0 +1,395 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import { localToUTC } from '../time-utils.js';
+import type { ElectionalHouseSystem } from '../types.js';
+import {
+  ASPECTS,
+  type ElectionalAspect,
+  type ElectionalContextResponse,
+  type ElectionalPhaseName,
+  PLANETS,
+  type PlanetName,
+  type PlanetPosition,
+  ZODIAC_SIGNS,
+} from '../types.js';
+import { parseDateOnlyInput } from './date-input.js';
+import type { GetElectionalContextInput, ServiceResult } from './service-types.js';
+import { normalizeLongitude } from './shared.js';
+
+interface ElectionalServiceDependencies {
+  ephem: EphemerisCalculator;
+  houseCalc: HouseCalculator;
+}
+
+const ELECTIONAL_CONTEXT_PLANET_IDS = [
+  PLANETS.SUN,
+  PLANETS.MOON,
+  PLANETS.MERCURY,
+  PLANETS.VENUS,
+  PLANETS.MARS,
+  PLANETS.JUPITER,
+  PLANETS.SATURN,
+  PLANETS.URANUS,
+  PLANETS.NEPTUNE,
+  PLANETS.PLUTO,
+];
+
+const ELECTIONAL_CONTEXT_HOUSE_SYSTEMS: ElectionalHouseSystem[] = ['P', 'K', 'W', 'R'];
+
+/**
+ * Internal electional workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns validation, deterministic instant resolution, sect/moon
+ * metadata, optional applying-aspect summaries, and readable electional text
+ * while the `AstroService` facade keeps the public contract stable.
+ */
+export class ElectionalService {
+  private readonly ephem: EphemerisCalculator;
+  private readonly houseCalc: HouseCalculator;
+
+  constructor(deps: ElectionalServiceDependencies) {
+    this.ephem = deps.ephem;
+    this.houseCalc = deps.houseCalc;
+  }
+
+  /**
+   * Produce deterministic electional context for a single local instant.
+   */
+  getElectionalContext(input: GetElectionalContextInput): ServiceResult<Record<string, unknown>> {
+    if (input.latitude < -90 || input.latitude > 90) {
+      throw new Error(`Invalid latitude: ${input.latitude} (must be between -90 and 90)`);
+    }
+    if (input.longitude < -180 || input.longitude > 180) {
+      throw new Error(`Invalid longitude: ${input.longitude} (must be between -180 and 180)`);
+    }
+
+    const houseSystem = input.house_system ?? 'P';
+    if (!ELECTIONAL_CONTEXT_HOUSE_SYSTEMS.includes(houseSystem)) {
+      throw new Error(
+        `Invalid house_system: ${houseSystem} (must be one of ${ELECTIONAL_CONTEXT_HOUSE_SYSTEMS.join(', ')})`
+      );
+    }
+
+    const includeRulerBasics = input.include_ruler_basics ?? false;
+    const includePlanetaryApplications = input.include_planetary_applications ?? true;
+    const orbDegrees = input.orb_degrees ?? 3;
+    if (!Number.isFinite(orbDegrees) || orbDegrees < 0.1 || orbDegrees > 10) {
+      throw new Error(`Invalid orb_degrees: ${orbDegrees} (must be between 0.1 and 10)`);
+    }
+
+    const parsedDate = parseDateOnlyInput(input.date);
+    const parsedTime = parseTimeOnlyInput(input.time);
+    let instantUtc: Date;
+    try {
+      instantUtc = localToUTC(
+        {
+          year: parsedDate.year,
+          month: parsedDate.month,
+          day: parsedDate.day,
+          hour: parsedTime.hour,
+          minute: parsedTime.minute,
+          second: parsedTime.second,
+        },
+        input.timezone,
+        'reject'
+      );
+    } catch (error) {
+      if (error instanceof RangeError) {
+        throw new Error(
+          `Invalid local electional time: ${input.date} ${input.time} in ${input.timezone} is ambiguous or nonexistent due to a DST transition.`
+        );
+      }
+      throw error;
+    }
+
+    const jdUt = this.ephem.dateToJulianDay(instantUtc);
+    const houses = this.houseCalc.calculateHouses(
+      jdUt,
+      input.latitude,
+      input.longitude,
+      houseSystem
+    );
+    const positions = this.ephem.getAllPlanets(jdUt, ELECTIONAL_CONTEXT_PLANET_IDS);
+
+    const sun = positions.find((position) => position.planet === 'Sun');
+    const moon = positions.find((position) => position.planet === 'Moon');
+    if (!sun || !moon) {
+      throw new Error('Ephemeris failed to compute Sun/Moon positions for electional context.');
+    }
+
+    const sunHorizontal = this.ephem.getHorizontalCoordinates(
+      jdUt,
+      sun,
+      input.longitude,
+      input.latitude
+    );
+    const rawSunAltitudeDegrees = sunHorizontal.trueAltitude;
+    const sunAltitudeDegrees = Number.parseFloat(rawSunAltitudeDegrees.toFixed(2));
+    const isDayChart = rawSunAltitudeDegrees >= 0;
+
+    const applyingAspects = includePlanetaryApplications
+      ? this.getElectionalApplyingAspects(positions, orbDegrees)
+      : undefined;
+    const moonApplyingAspects = applyingAspects?.filter(
+      (aspect) => aspect.from_body === 'Moon' || aspect.to_body === 'Moon'
+    );
+
+    const phaseAngle = Number.parseFloat(
+      normalizeLongitude(moon.longitude - sun.longitude).toFixed(2)
+    );
+    const warnings: string[] = [];
+    if (Math.abs(rawSunAltitudeDegrees) < 0.5) {
+      warnings.push('Sun is near the horizon; day/night classification is close to the boundary.');
+    }
+    warnings.push('Moon void-of-course is deferred in this slice and returns null.');
+    if (houses.system !== houseSystem) {
+      warnings.push(
+        `House calculation fell back from ${houseSystem} to ${houses.system} for this location.`
+      );
+    }
+
+    const ascLongitude = normalizeLongitude(houses.ascendant);
+    const ascSign = ZODIAC_SIGNS[Math.floor(ascLongitude / 30)];
+    const response: ElectionalContextResponse = {
+      input: {
+        date: input.date,
+        time: input.time,
+        timezone: input.timezone,
+        latitude: input.latitude,
+        longitude: input.longitude,
+        house_system: houses.system as ElectionalHouseSystem,
+        instant_utc: instantUtc.toISOString(),
+        jd_ut: Number.parseFloat(jdUt.toFixed(8)),
+      },
+      ascendant: {
+        longitude: Number.parseFloat(ascLongitude.toFixed(4)),
+        sign: ascSign,
+        degree_in_sign: Number.parseFloat((ascLongitude % 30).toFixed(4)),
+      },
+      sect: {
+        is_day_chart: isDayChart,
+        sun_altitude_degrees: sunAltitudeDegrees,
+        classification: isDayChart ? 'day' : 'night',
+      },
+      moon: {
+        longitude: Number.parseFloat(moon.longitude.toFixed(4)),
+        sign: moon.sign,
+        phase_angle: phaseAngle,
+        phase_name: this.getElectionalPhaseName(phaseAngle),
+        is_void_of_course: null,
+        ...(moonApplyingAspects !== undefined ? { applying_aspects: moonApplyingAspects } : {}),
+      },
+      meta: {
+        deterministic: true,
+        requires_natal: false,
+        warnings,
+        deferred_features: [
+          'robust_void_of_course',
+          'detailed_ruler_condition',
+          'house_context',
+          'natal_overlays',
+        ],
+      },
+    };
+
+    if (applyingAspects) {
+      response.applying_aspects = applyingAspects;
+    }
+
+    if (includeRulerBasics) {
+      const rulerBody = this.getTraditionalSignRuler(ascSign);
+      const rulerPosition = positions.find((position) => position.planet === rulerBody);
+      if (!rulerPosition) {
+        throw new Error(`Ephemeris failed to compute ASC ruler position for ${rulerBody}.`);
+      }
+      response.ruler_basics = {
+        asc_sign_ruler: {
+          body: rulerBody,
+          longitude: Number.parseFloat(rulerPosition.longitude.toFixed(4)),
+          sign: rulerPosition.sign,
+          speed: Number.parseFloat(rulerPosition.speed.toFixed(6)),
+          is_retrograde: rulerPosition.isRetrograde,
+        },
+      };
+    }
+
+    const humanText = [
+      `Electional context for ${input.date} ${input.time} (${input.timezone})`,
+      '',
+      `Ascendant: ${response.ascendant.degree_in_sign.toFixed(2)}° ${response.ascendant.sign}`,
+      `Sect: ${response.sect.classification} (${response.sect.sun_altitude_degrees.toFixed(2)}° Sun altitude)`,
+      `Moon: ${response.moon.phase_name} in ${response.moon.sign} (${response.moon.phase_angle.toFixed(2)}° phase angle)`,
+    ];
+
+    if (includePlanetaryApplications) {
+      const topLevelAspectText =
+        applyingAspects && applyingAspects.length > 0
+          ? applyingAspects
+              .slice(0, 5)
+              .map(
+                (aspect) =>
+                  `${aspect.from_body} ${aspect.aspect} ${aspect.to_body} (${aspect.orb.toFixed(2)}°)`
+              )
+              .join('\n')
+          : 'No applying aspects found within the configured orb.';
+
+      humanText.push('', 'Applying Aspects:', topLevelAspectText);
+    }
+
+    if (response.ruler_basics) {
+      humanText.push(
+        '',
+        `ASC Ruler: ${response.ruler_basics.asc_sign_ruler.body} in ${response.ruler_basics.asc_sign_ruler.sign} (${response.ruler_basics.asc_sign_ruler.longitude.toFixed(2)}°)`
+      );
+    }
+
+    if (warnings.length > 0) {
+      humanText.push('', `Warnings: ${warnings.join(' ')}`);
+    }
+
+    return {
+      data: response as unknown as Record<string, unknown>,
+      text: humanText.join('\n'),
+    };
+  }
+
+  /**
+   * Return only currently applying aspects inside the requested orb.
+   */
+  private getElectionalApplyingAspects(
+    positions: PlanetPosition[],
+    orbDegrees: number
+  ): ElectionalAspect[] {
+    const aspects: ElectionalAspect[] = [];
+
+    for (let i = 0; i < positions.length; i++) {
+      for (let j = i + 1; j < positions.length; j++) {
+        const from = positions[i];
+        const to = positions[j];
+        const currentAngle = this.ephem.calculateAspectAngle(from.longitude, to.longitude);
+
+        for (const aspect of ASPECTS) {
+          const orb = Math.abs(currentAngle - aspect.angle);
+          if (orb > aspect.orb || orb > orbDegrees) {
+            continue;
+          }
+
+          const applying = this.isElectionalAspectApplying(from, to, aspect.angle);
+          if (!applying) {
+            continue;
+          }
+
+          aspects.push({
+            from_body: from.planet,
+            to_body: to.planet,
+            aspect: aspect.name,
+            orb: Number.parseFloat(orb.toFixed(4)),
+            applying: true,
+          });
+        }
+      }
+    }
+
+    return aspects.sort(
+      (a, b) =>
+        a.orb - b.orb ||
+        a.from_body.localeCompare(b.from_body) ||
+        a.to_body.localeCompare(b.to_body) ||
+        a.aspect.localeCompare(b.aspect)
+    );
+  }
+
+  /**
+   * Determine whether a near-aspect is applying instead of separating.
+   */
+  private isElectionalAspectApplying(
+    from: Pick<PlanetPosition, 'longitude' | 'speed'>,
+    to: Pick<PlanetPosition, 'longitude' | 'speed'>,
+    aspectAngle: number
+  ): boolean {
+    const signedSeparation = this.getSignedAngularDifference(from.longitude, to.longitude);
+    const currentSeparation = Math.abs(signedSeparation);
+    if (currentSeparation === aspectAngle) {
+      return false;
+    }
+
+    const separationRate = Math.sign(signedSeparation || 1) * (to.speed - from.speed);
+    if (separationRate === 0) {
+      return false;
+    }
+
+    return currentSeparation < aspectAngle ? separationRate > 0 : separationRate < 0;
+  }
+
+  /**
+   * Compute the signed shortest angular distance in degrees.
+   */
+  private getSignedAngularDifference(fromLongitude: number, toLongitude: number): number {
+    const normalized = ((toLongitude - fromLongitude + 540) % 360) - 180;
+    return normalized === -180 ? 180 : normalized;
+  }
+
+  /**
+   * Bucket a Sun-Moon phase angle into the service's coarse phase names.
+   */
+  private getElectionalPhaseName(phaseAngle: number): ElectionalPhaseName {
+    if (phaseAngle < 45) return 'new';
+    if (phaseAngle < 90) return 'crescent';
+    if (phaseAngle < 135) return 'first_quarter';
+    if (phaseAngle < 180) return 'gibbous';
+    if (phaseAngle < 225) return 'full';
+    if (phaseAngle < 270) return 'disseminating';
+    if (phaseAngle < 315) return 'last_quarter';
+    return 'balsamic';
+  }
+
+  /**
+   * Return the traditional ruler used for the ascendant sign summary.
+   */
+  private getTraditionalSignRuler(sign: string): PlanetName {
+    const signRulers: Record<string, PlanetName> = {
+      Aries: 'Mars',
+      Taurus: 'Venus',
+      Gemini: 'Mercury',
+      Cancer: 'Moon',
+      Leo: 'Sun',
+      Virgo: 'Mercury',
+      Libra: 'Venus',
+      Scorpio: 'Mars',
+      Sagittarius: 'Jupiter',
+      Capricorn: 'Saturn',
+      Aquarius: 'Saturn',
+      Pisces: 'Jupiter',
+    };
+
+    return signRulers[sign] ?? 'Mars';
+  }
+}
+
+/**
+ * Parse a strict local wall-clock time for electional requests.
+ */
+function parseTimeOnlyInput(timeStr: string): { hour: number; minute: number; second: number } {
+  const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(timeStr);
+  if (!match) {
+    throw new Error(`Invalid time format: expected HH:mm[:ss], got "${timeStr}"`);
+  }
+
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  const second = match[3] === undefined ? 0 : Number(match[3]);
+
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59) {
+    throw new Error(`Invalid clock time: ${timeStr}`);
+  }
+
+  try {
+    Temporal.PlainTime.from({ hour, minute, second });
+  } catch {
+    throw new Error(`Invalid clock time: ${timeStr}`);
+  }
+
+  return { hour, minute, second };
+}

package/src/astro-service/natal-service.ts

@@ -0,0 +1,235 @@
+import type { McpStartupDefaults } from '../entrypoint.js';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import { type HouseSystem, type NatalChart, PLANETS, ZODIAC_SIGNS } from '../types.js';
+import type { GetHousesInput, ServiceResult, SetNatalChartInput } from './service-types.js';
+import { resolveHouseSystem } from './shared.js';
+
+interface NatalServiceDependencies {
+  ephem: EphemerisCalculator;
+  houseCalc: HouseCalculator;
+  mcpStartupDefaults: Readonly<McpStartupDefaults>;
+  isInitialized: () => boolean;
+}
+
+/**
+ * Internal natal/chart-state workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns natal chart initialization, house resolution, and basic
+ * server-status serialization while the public `AstroService` facade preserves
+ * the existing contract for MCP and CLI callers.
+ */
+export class NatalService {
+  private readonly ephem: EphemerisCalculator;
+  private readonly houseCalc: HouseCalculator;
+  private readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
+  private readonly isInitialized: () => boolean;
+
+  constructor(deps: NatalServiceDependencies) {
+    this.ephem = deps.ephem;
+    this.houseCalc = deps.houseCalc;
+    this.mcpStartupDefaults = deps.mcpStartupDefaults;
+    this.isInitialized = deps.isInitialized;
+  }
+
+  /**
+   * Build and cache the shared natal chart payload used by later workflows.
+   */
+  setNatalChart(
+    input: SetNatalChartInput
+  ): ServiceResult<Record<string, unknown>> & { chart: NatalChart } {
+    const requestedHouseSystem = input.house_system ?? null;
+
+    const chart: NatalChart = {
+      name: input.name,
+      birthDate: {
+        year: input.year,
+        month: input.month,
+        day: input.day,
+        hour: input.hour,
+        minute: input.minute,
+      },
+      location: {
+        latitude: input.latitude,
+        longitude: input.longitude,
+        timezone: input.timezone,
+      },
+    };
+
+    const birthTimeDisambiguation = input.birth_time_disambiguation ?? 'reject';
+    const utcDate = localToUTC(chart.birthDate, chart.location.timezone, birthTimeDisambiguation);
+    const utcComponents = utcToLocal(utcDate, 'UTC');
+
+    const jd = this.ephem.dateToJulianDay(utcDate);
+    const planetIds = Object.values(PLANETS);
+    const positions = this.ephem.getAllPlanets(jd, planetIds);
+
+    const isPolar = Math.abs(chart.location.latitude) > 66;
+    let houseSystem: HouseSystem = requestedHouseSystem || 'P';
+    if (isPolar && houseSystem === 'P') {
+      houseSystem = 'W';
+    }
+
+    const houses = this.houseCalc.calculateHouses(
+      jd,
+      chart.location.latitude,
+      chart.location.longitude,
+      houseSystem
+    );
+
+    const storedChart: NatalChart = {
+      ...chart,
+      planets: positions,
+      julianDay: jd,
+      houseSystem: houses.system,
+      requestedHouseSystem: requestedHouseSystem ?? undefined,
+      utcDateTime: utcComponents,
+    };
+
+    const sun = positions.find((position) => position.planet === 'Sun');
+    const moon = positions.find((position) => position.planet === 'Moon');
+    if (!sun || !moon) {
+      throw new Error('Ephemeris failed to compute Sun/Moon positions for natal chart.');
+    }
+
+    const formatDegree = (longitude: number): string => {
+      const sign = ZODIAC_SIGNS[Math.floor(longitude / 30)];
+      const degree = longitude % 30;
+      return `${degree.toFixed(0)}° ${sign}`;
+    };
+
+    const localTimeStr = `${chart.birthDate.month}/${chart.birthDate.day}/${chart.birthDate.year} ${chart.birthDate.hour}:${String(chart.birthDate.minute).padStart(2, '0')}`;
+    const utcTimeStr = `${utcComponents.month}/${utcComponents.day}/${utcComponents.year} ${utcComponents.hour}:${String(utcComponents.minute).padStart(2, '0')} UTC`;
+
+    const systemNames: Record<string, string> = {
+      P: 'Placidus',
+      W: 'Whole Sign',
+      K: 'Koch',
+      E: 'Equal',
+    };
+
+    const latDir = chart.location.latitude >= 0 ? 'N' : 'S';
+    const lonDir = chart.location.longitude >= 0 ? 'E' : 'W';
+    const latAbs = Math.abs(chart.location.latitude);
+    const lonAbs = Math.abs(chart.location.longitude);
+
+    const feedback = [
+      `Natal chart saved for ${chart.name}`,
+      '',
+      'Birth Details:',
+      `- Local Time: ${localTimeStr} (${chart.location.timezone})`,
+      `- UTC Time: ${utcTimeStr}`,
+      `- Location: ${latAbs.toFixed(2)}°${latDir}, ${lonAbs.toFixed(2)}°${lonDir}`,
+      '',
+      'Chart Angles:',
+      `- Sun: ${formatDegree(sun.longitude)}`,
+      `- Moon: ${formatDegree(moon.longitude)}`,
+      `- Ascendant: ${formatDegree(houses.ascendant)}`,
+      `- MC: ${formatDegree(houses.mc)}`,
+      '',
+      `House System: ${systemNames[houses.system] || houses.system}`,
+    ];
+
+    if (isPolar && houses.system !== houseSystem) {
+      feedback.push(
+        '',
+        `Note: Polar latitude detected (${chart.location.latitude.toFixed(1)}°). Requested ${systemNames[houseSystem]}, using ${systemNames[houses.system]} instead.`
+      );
+    } else if (isPolar) {
+      feedback.push(
+        '',
+        `Note: Polar latitude detected (${chart.location.latitude.toFixed(1)}°). Using ${systemNames[houses.system]} house system.`
+      );
+    }
+
+    const structuredData: Record<string, unknown> = {
+      name: chart.name,
+      birthTime: {
+        local: localTimeStr,
+        utc: utcTimeStr,
+        timezone: chart.location.timezone,
+      },
+      location: {
+        latitude: chart.location.latitude,
+        longitude: chart.location.longitude,
+      },
+      julianDay: jd,
+      requestedHouseSystem,
+      resolvedHouseSystem: houses.system,
+      angles: {
+        sun: formatDegree(sun.longitude),
+        moon: formatDegree(moon.longitude),
+        ascendant: formatDegree(houses.ascendant),
+        mc: formatDegree(houses.mc),
+      },
+      isPolar,
+    };
+
+    return {
+      chart: storedChart,
+      data: structuredData,
+      text: feedback.join('\n'),
+    };
+  }
+
+  /**
+   * Calculate house cusps and angles for a natal chart.
+   */
+  getHouses(
+    natalChart: NatalChart,
+    input: GetHousesInput = {}
+  ): ServiceResult<Record<string, unknown>> {
+    const system = resolveHouseSystem(natalChart, this.mcpStartupDefaults, input.system);
+    if (!natalChart.julianDay) {
+      throw new Error('Natal chart is missing julianDay. Re-run set_natal_chart to fix.');
+    }
+
+    const houses = this.houseCalc.calculateHouses(
+      natalChart.julianDay,
+      natalChart.location.latitude,
+      natalChart.location.longitude,
+      system
+    );
+
+    const humanLines = houses.cusps
+      .slice(1)
+      .map((degree, index) => {
+        const sign = ZODIAC_SIGNS[Math.floor(degree / 30)];
+        return `House ${index + 1}: ${(degree % 30).toFixed(2)}° ${sign}`;
+      })
+      .join('\n');
+    const humanText = `Houses (${houses.system}):\nAsc: ${houses.ascendant.toFixed(2)}° | MC: ${houses.mc.toFixed(2)}°\n\n${humanLines}`;
+
+    return {
+      data: houses as unknown as Record<string, unknown>,
+      text: humanText,
+    };
+  }
+
+  /**
+   * Summarize process-local server state and configured startup defaults.
+   */
+  getServerStatus(natalChart: NatalChart | null): ServiceResult<Record<string, unknown>> {
+    const statusData = {
+      serverVersion: '1.0.0',
+      hasNatalChart: natalChart !== null,
+      natalChartName: natalChart?.name ?? null,
+      natalChartTimezone: natalChart?.location.timezone ?? null,
+      startupDefaults: {
+        preferredTimezone: this.mcpStartupDefaults.preferredTimezone ?? null,
+        preferredHouseStyle: this.mcpStartupDefaults.preferredHouseStyle ?? null,
+        weekdayLabels: this.mcpStartupDefaults.weekdayLabels ?? null,
+      },
+      ephemerisInitialized: this.isInitialized(),
+      stateModel: 'stateful-per-process',
+    };
+
+    const humanText = natalChart
+      ? `Server ready. Natal chart loaded: ${natalChart.name} (${natalChart.location.timezone})`
+      : 'Server ready. No natal chart loaded — call set_natal_chart first.';
+
+    return { data: statusData, text: humanText };
+  }
+}