ether-to-astro 1.2.0 → 1.3.0

package/src/astro-service/rising-sign-service.ts

@@ -0,0 +1,181 @@
+import type { EphemerisCalculator } from '../ephemeris.js';
+import { formatInTimezone } from '../formatter.js';
+import type { HouseCalculator } from '../houses.js';
+import {
+  addLocalDays,
+  formatLocalTimestampWithOffset,
+  localToUTC,
+  utcToLocal,
+} from '../time-utils.js';
+import { ZODIAC_SIGNS } from '../types.js';
+import { parseDateOnlyInput } from './date-input.js';
+import type { GetRisingSignWindowsInput, ServiceResult } from './service-types.js';
+import { normalizeLongitude } from './shared.js';
+
+interface RisingSignServiceDependencies {
+  ephem: EphemerisCalculator;
+  houseCalc: HouseCalculator;
+}
+
+/**
+ * Internal rising-sign window scanner used by `AstroService`.
+ *
+ * @remarks
+ * This module owns the local-day scan, optional exact-boundary refinement, and
+ * serialization of sign windows while the public facade keeps the same method
+ * signature and result shape.
+ */
+export class RisingSignService {
+  private readonly ephem: EphemerisCalculator;
+  private readonly houseCalc: HouseCalculator;
+
+  constructor(deps: RisingSignServiceDependencies) {
+    this.ephem = deps.ephem;
+    this.houseCalc = deps.houseCalc;
+  }
+
+  /**
+   * Find rising-sign windows across a local calendar day.
+   */
+  getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>> {
+    const mode = input.mode ?? 'approximate';
+    if (mode !== 'approximate' && mode !== 'exact') {
+      throw new Error(`Invalid mode: ${mode} (must be approximate or exact)`);
+    }
+    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 parsed = parseDateOnlyInput(input.date);
+    try {
+      utcToLocal(new Date(), input.timezone);
+    } catch {
+      throw new Error(`Invalid timezone: ${input.timezone}`);
+    }
+
+    const dayStartLocal = {
+      year: parsed.year,
+      month: parsed.month,
+      day: parsed.day,
+      hour: 0,
+      minute: 0,
+      second: 0,
+    };
+    const dayStartUtc = localToUTC(dayStartLocal, input.timezone);
+    const dayEndUtc = addLocalDays(dayStartLocal, input.timezone, 1);
+
+    const stepMs = mode === 'exact' ? 60 * 60 * 1000 : 2 * 60 * 60 * 1000;
+    const probeStepMs = mode === 'exact' ? 5 * 60 * 1000 : 30 * 60 * 1000;
+    const boundaries: Date[] = [dayStartUtc];
+    let cursor = dayStartUtc;
+    while (cursor < dayEndUtc) {
+      const next = new Date(Math.min(cursor.getTime() + stepMs, dayEndUtc.getTime()));
+      boundaries.push(...this.findSignTransitionsInBucket(input, mode, cursor, next, probeStepMs));
+      cursor = next;
+    }
+    boundaries.push(dayEndUtc);
+
+    const windows = boundaries.slice(0, -1).map((start, index) => {
+      const end = boundaries[index + 1];
+      const sample = new Date((start.getTime() + end.getTime()) / 2);
+      const sign = this.getAscSign(input, sample).sign;
+      return {
+        sign,
+        start: formatLocalTimestampWithOffset(start, input.timezone),
+        end: formatLocalTimestampWithOffset(end, input.timezone),
+        durationMs: end.getTime() - start.getTime(),
+      };
+    });
+
+    const structuredData = {
+      date: input.date,
+      timezone: input.timezone,
+      location: {
+        latitude: input.latitude,
+        longitude: input.longitude,
+      },
+      mode,
+      windows,
+    };
+
+    const humanText = `Rising Sign Windows (${input.date}, ${input.timezone}, ${mode}):\n\n${windows
+      .map(
+        (window) =>
+          `${window.sign}: ${formatInTimezone(new Date(window.start), input.timezone)} → ${formatInTimezone(new Date(window.end), input.timezone)}`
+      )
+      .join('\n')}`;
+
+    return {
+      data: structuredData,
+      text: humanText,
+    };
+  }
+
+  /**
+   * Sample the ascendant sign for a specific moment.
+   */
+  private getAscSign(
+    input: Pick<GetRisingSignWindowsInput, 'latitude' | 'longitude'>,
+    date: Date
+  ): { sign: string; longitude: number } {
+    const jd = this.ephem.dateToJulianDay(date);
+    const houses = this.houseCalc.calculateHouses(jd, input.latitude, input.longitude, 'P');
+    const normalized = normalizeLongitude(houses.ascendant);
+    return { sign: ZODIAC_SIGNS[Math.floor(normalized / 30)], longitude: normalized };
+  }
+
+  /**
+   * Binary-search a sign change down to a stable exact-mode boundary.
+   */
+  private refineBoundary(
+    input: Pick<GetRisingSignWindowsInput, 'latitude' | 'longitude'>,
+    left: Date,
+    right: Date
+  ): Date {
+    const leftSign = this.getAscSign(input, left).sign;
+    let lo = left;
+    let hi = right;
+    for (let i = 0; i < 25; i++) {
+      const mid = new Date((lo.getTime() + hi.getTime()) / 2);
+      const midSign = this.getAscSign(input, mid).sign;
+      if (midSign === leftSign) {
+        lo = mid;
+      } else {
+        hi = mid;
+      }
+    }
+    return hi;
+  }
+
+  /**
+   * Probe a scan bucket and emit every sign transition inside it.
+   */
+  private findSignTransitionsInBucket(
+    input: Pick<GetRisingSignWindowsInput, 'latitude' | 'longitude'>,
+    mode: 'approximate' | 'exact',
+    start: Date,
+    end: Date,
+    probeStepMs: number
+  ): Date[] {
+    const boundaries: Date[] = [];
+    let probeCursor = start;
+    let currentSign = this.getAscSign(input, probeCursor).sign;
+
+    while (probeCursor < end) {
+      const probeNext = new Date(Math.min(probeCursor.getTime() + probeStepMs, end.getTime()));
+      const nextSign = this.getAscSign(input, probeNext).sign;
+      if (nextSign !== currentSign) {
+        boundaries.push(
+          mode === 'exact' ? this.refineBoundary(input, probeCursor, probeNext) : probeNext
+        );
+      }
+      probeCursor = probeNext;
+      currentSign = nextSign;
+    }
+
+    return boundaries;
+  }
+}

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

@@ -0,0 +1,90 @@
+import type { Disambiguation } from '../time-utils.js';
+import type { ElectionalHouseSystem, HouseSystem } from '../types.js';
+
+/**
+ * Public input type for building and caching the shared natal chart payload.
+ */
+export interface SetNatalChartInput {
+  name: string;
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  house_system?: HouseSystem;
+  birth_time_disambiguation?: Disambiguation;
+}
+
+/**
+ * Public input type for querying natal transits.
+ */
+export interface GetTransitsInput {
+  date?: string;
+  categories?: string[];
+  include_mundane?: boolean;
+  days_ahead?: number;
+  mode?: 'snapshot' | 'best_hit' | 'forecast';
+  max_orb?: number;
+  exact_only?: boolean;
+  applying_only?: boolean;
+}
+
+/**
+ * Public input type for stateless electional context lookup.
+ */
+export interface GetElectionalContextInput {
+  date: string;
+  time: string;
+  timezone: string;
+  latitude: number;
+  longitude: number;
+  house_system?: ElectionalHouseSystem;
+  include_ruler_basics?: boolean;
+  include_planetary_applications?: boolean;
+  orb_degrees?: number;
+}
+
+/**
+ * Public input type for house lookup on an existing natal chart.
+ */
+export interface GetHousesInput {
+  system?: string;
+}
+
+/**
+ * Public input type for daily rising-sign window lookup.
+ */
+export interface GetRisingSignWindowsInput {
+  date: string;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  mode?: 'approximate' | 'exact';
+}
+
+/**
+ * Public output-wrapper shared by service methods that return data plus text.
+ */
+export interface ServiceResult<T> {
+  data: T;
+  text: string;
+}
+
+/**
+ * Public input type for chart rendering methods.
+ */
+export interface GenerateChartInput {
+  theme?: 'light' | 'dark';
+  format?: 'svg' | 'png' | 'webp';
+  output_path?: string;
+}
+
+/**
+ * Public input type for transit-chart rendering methods.
+ */
+export interface GenerateTransitChartInput extends GenerateChartInput {
+  date?: string;
+}

package/src/astro-service/shared.ts

@@ -0,0 +1,128 @@
+import type { McpStartupDefaults } from '../entrypoint.js';
+import { type HouseData, type HouseSystem, type NatalChart, ZODIAC_SIGNS } from '../types.js';
+
+/**
+ * Normalize any longitude into the standard 0-360 range.
+ *
+ * @param longitude - Raw longitude in degrees, including negative or >360 values
+ * @returns Longitude normalized into the half-open interval [0, 360)
+ */
+export function normalizeLongitude(longitude: number): number {
+  return ((longitude % 360) + 360) % 360;
+}
+
+/**
+ * Convert a raw longitude into zodiac sign and in-sign degree.
+ *
+ * @param longitude - Raw longitude in degrees
+ * @returns Sign name plus degree within that sign
+ *
+ * @remarks
+ * Rounded degree values that would otherwise land on 30.00 are carried into
+ * the next sign so serialized placement stays astrologically valid.
+ */
+export function getSignAndDegree(longitude: number): { sign: string; degree: number } {
+  const normalized = normalizeLongitude(longitude);
+  const baseSignIndex = Math.floor(normalized / 30);
+  const roundedDegree = Number.parseFloat((normalized % 30).toFixed(2));
+  const shouldCarryToNextSign = roundedDegree >= 30;
+  const signIndex = shouldCarryToNextSign
+    ? (baseSignIndex + 1) % ZODIAC_SIGNS.length
+    : baseSignIndex;
+
+  return {
+    sign: ZODIAC_SIGNS[signIndex],
+    degree: shouldCarryToNextSign ? 0 : roundedDegree,
+  };
+}
+
+/**
+ * Map a longitude to its house number for a resolved house table.
+ *
+ * @param longitude - Longitude to place into a house
+ * @param houses - Resolved house cusps for the relevant chart or moment
+ * @returns 1-based house number
+ */
+export function getHouseNumber(longitude: number, houses: HouseData): number {
+  const normalized = normalizeLongitude(longitude);
+
+  for (let house = 1; house <= 12; house++) {
+    const start = normalizeLongitude(houses.cusps[house]);
+    const nextHouse = house === 12 ? 1 : house + 1;
+    const end = normalizeLongitude(houses.cusps[nextHouse]);
+    const span = (end - start + 360) % 360;
+    const offset = (normalized - start + 360) % 360;
+
+    if (span === 0 || offset === 0 || offset < span) {
+      return house;
+    }
+  }
+
+  return 12;
+}
+
+/**
+ * Resolve the house system precedence shared by service entrypoints.
+ *
+ * @param natalChart - Natal chart carrying stored and requested house system state
+ * @param startupDefaults - Process startup defaults that can provide fallback policy
+ * @param explicitSystem - Per-call override when the caller requested a specific system
+ * @returns Final house system to use for the calculation
+ */
+export function resolveHouseSystem(
+  natalChart: NatalChart,
+  startupDefaults: Readonly<McpStartupDefaults>,
+  explicitSystem?: string
+): HouseSystem {
+  return (explicitSystem ||
+    natalChart.requestedHouseSystem ||
+    startupDefaults.preferredHouseStyle ||
+    natalChart.houseSystem ||
+    'P') as HouseSystem;
+}
+
+/**
+ * Resolve the reporting timezone precedence shared by service entrypoints.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used as fallback
+ * @returns Final reporting timezone for text and date labels
+ */
+export function resolveReportingTimezone(
+  startupDefaults: Readonly<McpStartupDefaults>,
+  explicitTimezone?: string,
+  natalTimezone?: string
+): string {
+  return explicitTimezone ?? startupDefaults.preferredTimezone ?? natalTimezone ?? 'UTC';
+}
+
+/**
+ * Resolve both calculation and reporting timezones for chart-based workflows.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitReportingTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used for local-day interpretation
+ * @returns Calculation timezone plus reporting timezone
+ *
+ * @remarks
+ * Calculation timezone controls local-day math and ephemeris lookups. Reporting
+ * timezone controls user-facing labels and formatted timestamps.
+ */
+export function resolveTimezones(
+  startupDefaults: Readonly<McpStartupDefaults>,
+  explicitReportingTimezone?: string,
+  natalTimezone?: string
+): {
+  calculationTimezone: string;
+  reportingTimezone: string;
+} {
+  return {
+    calculationTimezone: natalTimezone ?? 'UTC',
+    reportingTimezone: resolveReportingTimezone(
+      startupDefaults,
+      explicitReportingTimezone,
+      natalTimezone
+    ),
+  };
+}

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

@@ -0,0 +1,191 @@
+import type { EclipseCalculator } from '../eclipses.js';
+import type { McpStartupDefaults } from '../entrypoint.js';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { RiseSetCalculator } from '../riseset.js';
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import { ASTEROIDS, type NatalChart, NODES, PLANETS } from '../types.js';
+import type { ServiceResult } from './service-types.js';
+import { resolveReportingTimezone } from './shared.js';
+
+interface SkyServiceDependencies {
+  ephem: EphemerisCalculator;
+  riseSetCalc: RiseSetCalculator;
+  eclipseCalc: EclipseCalculator;
+  mcpStartupDefaults: Readonly<McpStartupDefaults>;
+  now: () => Date;
+  formatTimestamp: (date: Date, timezone: string) => string;
+}
+
+/**
+ * Internal current-sky and runtime lookup workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns read-only runtime lookups that depend on "now", including
+ * retrogrades, asteroid/node snapshots, rise/set tables, and eclipse queries.
+ */
+export class SkyService {
+  private readonly ephem: EphemerisCalculator;
+  private readonly riseSetCalc: RiseSetCalculator;
+  private readonly eclipseCalc: EclipseCalculator;
+  private readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
+  private readonly now: () => Date;
+  private readonly formatTimestamp: (date: Date, timezone: string) => string;
+
+  constructor(deps: SkyServiceDependencies) {
+    this.ephem = deps.ephem;
+    this.riseSetCalc = deps.riseSetCalc;
+    this.eclipseCalc = deps.eclipseCalc;
+    this.mcpStartupDefaults = deps.mcpStartupDefaults;
+    this.now = deps.now;
+    this.formatTimestamp = deps.formatTimestamp;
+  }
+
+  /**
+   * Return the currently retrograde planets for the requested reporting timezone.
+   */
+  getRetrogradePlanets(timezone?: string): ServiceResult<Record<string, unknown>> {
+    const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+    const now = this.now();
+    const jd = this.ephem.dateToJulianDay(now);
+    const positions = this.ephem.getAllPlanets(jd, Object.values(PLANETS));
+    const retrograde = positions.filter((position) => position.isRetrograde);
+
+    const structuredData = {
+      date: this.getDateLabel(now, resolvedTimezone),
+      timezone: resolvedTimezone,
+      planets: retrograde,
+    };
+
+    const humanText =
+      retrograde.length === 0
+        ? 'No planets are currently retrograde.'
+        : `Retrograde Planets:\n\n${retrograde.map((position) => `${position.planet}: ${position.degree.toFixed(2)}° ${position.sign}`).join('\n')}`;
+
+    return { data: structuredData, text: humanText };
+  }
+
+  /**
+   * Return the next rise and set events after the local day anchor for the chart location.
+   */
+  async getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>> {
+    const timezone = natalChart.location.timezone;
+    const reportingTimezone = this.mcpStartupDefaults.preferredTimezone || timezone;
+    const now = this.now();
+    const localNow = utcToLocal(now, timezone);
+    const localMidnight = {
+      year: localNow.year,
+      month: localNow.month,
+      day: localNow.day,
+      hour: 0,
+      minute: 0,
+      second: 0,
+    };
+    const midnightUTC = localToUTC(localMidnight, timezone);
+
+    const results = await this.riseSetCalc.getAllRiseSet(
+      midnightUTC,
+      natalChart.location.latitude,
+      natalChart.location.longitude
+    );
+
+    const structuredData = {
+      date: this.getDateLabel(now, timezone),
+      timezone,
+      times: results.map((result) => ({
+        planet: result.planet,
+        rise: result.rise?.toISOString() ?? null,
+        set: result.set?.toISOString() ?? null,
+      })),
+    };
+
+    const humanText = `Rise/Set Times:\n\n${results
+      .map((result) => {
+        const rise = result.rise ? this.formatTimestamp(result.rise, reportingTimezone) : 'none';
+        const set = result.set ? this.formatTimestamp(result.set, reportingTimezone) : 'none';
+        return `${result.planet}: Rise ${rise}, Set ${set}`;
+      })
+      .join('\n')}`;
+
+    return {
+      data: structuredData,
+      text: humanText,
+    };
+  }
+
+  /**
+   * Return current asteroid and node positions for the requested reporting timezone.
+   */
+  getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>> {
+    const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+    const now = this.now();
+    const jd = this.ephem.dateToJulianDay(now);
+    const positions = this.ephem.getAllPlanets(jd, [...ASTEROIDS, ...NODES]);
+
+    const structuredData = {
+      date: this.getDateLabel(now, resolvedTimezone),
+      timezone: resolvedTimezone,
+      positions,
+    };
+
+    const humanText = `Asteroid & Node Positions:\n\n${positions
+      .map((position) => {
+        const retrogradeLabel = position.isRetrograde ? ' Rx' : '';
+        return `${position.planet}: ${position.degree.toFixed(2)}° ${position.sign}${retrogradeLabel}`;
+      })
+      .join('\n')}`;
+
+    return {
+      data: structuredData,
+      text: humanText,
+    };
+  }
+
+  /**
+   * Look up the next solar and lunar eclipses after the current instant.
+   */
+  getNextEclipses(timezone?: string): ServiceResult<Record<string, unknown>> {
+    const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+    const jd = this.ephem.dateToJulianDay(this.now());
+
+    const solarEclipse = this.eclipseCalc.findNextSolarEclipse(jd);
+    const lunarEclipse = this.eclipseCalc.findNextLunarEclipse(jd);
+
+    const eclipses: Array<{ type: string; eclipseType: string; maxTime: string }> = [];
+    const humanLines: string[] = [];
+
+    if (solarEclipse) {
+      eclipses.push({
+        type: solarEclipse.type,
+        eclipseType: solarEclipse.eclipseType,
+        maxTime: solarEclipse.maxTime.toISOString(),
+      });
+      humanLines.push(
+        `Next Solar Eclipse: ${this.formatTimestamp(solarEclipse.maxTime, resolvedTimezone)} (${solarEclipse.eclipseType})`
+      );
+    }
+
+    if (lunarEclipse) {
+      eclipses.push({
+        type: lunarEclipse.type,
+        eclipseType: lunarEclipse.eclipseType,
+        maxTime: lunarEclipse.maxTime.toISOString(),
+      });
+      humanLines.push(
+        `Next Lunar Eclipse: ${this.formatTimestamp(lunarEclipse.maxTime, resolvedTimezone)} (${lunarEclipse.eclipseType})`
+      );
+    }
+
+    const structuredData = { timezone: resolvedTimezone, eclipses };
+    const humanText =
+      eclipses.length === 0
+        ? 'No eclipses found in the near future.'
+        : `Upcoming Eclipses:\n\n${humanLines.join('\n')}`;
+
+    return { data: structuredData, text: humanText };
+  }
+
+  private getDateLabel(date: Date, timezone: string): string {
+    const localDate = utcToLocal(date, timezone);
+    return `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
+  }
+}