ether-to-astro 1.0.0

package/dist/riseset.js

@@ -0,0 +1,185 @@
+import { constants as Constants } from 'sweph';
+import { logger } from './logger.js';
+import { PLANET_NAMES } from './types.js';
+/**
+ * Calculator for rise, set, and meridian transit times
+ *
+ * @remarks
+ * Calculates when celestial bodies rise above and set below the horizon,
+ * plus upper and lower meridian transits. Handles circumpolar objects
+ * and atmospheric refraction corrections.
+ */
+export class RiseSetCalculator {
+    /** Ephemeris calculator instance */
+    ephem;
+    /**
+     * Create a new rise/set calculator
+     *
+     * @param ephem - Initialized ephemeris calculator
+     * @throws Error if ephemeris is not initialized
+     *
+     * @remarks
+     * The ephemeris calculator must be initialized before passing
+     * to the RiseSetCalculator constructor.
+     */
+    constructor(ephem) {
+        this.ephem = ephem;
+    }
+    /**
+     * Calculate rise, set, and meridian transit times for a celestial body
+     *
+     * Uses standard astronomical definitions:
+     * - Rise/Set: Upper limb of disc with atmospheric refraction considered
+     * - Atmospheric pressure: Estimated from altitude (sea level if altitude=0)
+     * - Temperature: 0°C (default assumption)
+     * - Upper meridian: Highest point in sky (culmination)
+     * - Lower meridian: Lowest point in sky (anti-culmination)
+     *
+     * Swiss Ephemeris return codes:
+     * - 0 or positive: Event found successfully
+     * - -1: Calculation error (hard failure)
+     * - -2: No event exists (circumpolar object)
+     *
+     * @param julianDay - Julian Day to start search from (typically midnight of target date)
+     * @param planetId - Swiss Ephemeris planet ID
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0 = sea level)
+     * @returns Rise/set/transit times, or undefined fields if event doesn't occur
+     * @throws {Error} If ephemeris not initialized, invalid inputs, or hard calculation error
+     */
+    calculateRiseSet(julianDay, planetId, latitude, longitude, altitude = 0) {
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        // Input validation
+        if (!Number.isFinite(julianDay)) {
+            throw new Error('Invalid Julian Day: must be a finite number');
+        }
+        if (latitude < -90 || latitude > 90) {
+            throw new Error(`Invalid latitude: ${latitude} (must be -90 to 90)`);
+        }
+        if (!Number.isFinite(longitude)) {
+            throw new Error('Invalid longitude: must be a finite number');
+        }
+        if (!Number.isFinite(altitude)) {
+            throw new Error('Invalid altitude: must be a finite number');
+        }
+        const planetName = PLANET_NAMES[planetId];
+        if (!planetName) {
+            throw new Error(`Unknown planet ID: ${planetId}`);
+        }
+        const result = {
+            planet: planetName,
+        };
+        // Helper to call rise_trans and handle return codes
+        const calculateEvent = (eventType, eventName) => {
+            const eventResult = this.ephem.eph.rise_trans(julianDay, planetId, null, Constants.SEFLG_SWIEPH, eventType, [longitude, latitude, altitude], 0, // atpress: 0 = auto-estimate from altitude
+            0 // attemp: 0°C
+            );
+            if (eventResult.flag === -1) {
+                throw new Error(`${eventName} calculation failed for ${planetName}: ${eventResult.error || 'Unknown error'}`);
+            }
+            else if (eventResult.flag === -2) {
+                logger.debug(`No ${eventName} for ${planetName} (circumpolar or no event)`, {
+                    planet: planetName,
+                    latitude,
+                });
+                return undefined;
+            }
+            else if (Number.isFinite(eventResult.data)) {
+                return this.ephem.julianDayToDate(eventResult.data);
+            }
+            return undefined;
+        };
+        result.rise = calculateEvent(Constants.SE_CALC_RISE, 'rise');
+        result.set = calculateEvent(Constants.SE_CALC_SET, 'set');
+        result.upperMeridianTransit = calculateEvent(Constants.SE_CALC_MTRANSIT, 'upper meridian transit');
+        result.lowerMeridianTransit = calculateEvent(Constants.SE_CALC_ITRANSIT, 'lower meridian transit');
+        return result;
+    }
+    /**
+     * Get rise/set times for all planets for a given date
+     *
+     * @param date - Date/time to use as search anchor (typically current instant or midnight of target date)
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Array of rise/set times for all planets
+     * @throws Error if ephemeris not initialized or invalid inputs
+     *
+     * @remarks
+     * Calculates for Sun through Pluto. Some fields may be undefined
+     * for circumpolar objects at extreme latitudes.
+     *
+     * Swiss Ephemeris searches for the NEXT event after the given instant,
+     * so to get events for a specific civil date, pass midnight of that date.
+     */
+    async getAllRiseSet(date, latitude, longitude, altitude = 0) {
+        // Validate shared inputs once - these are configuration errors, not planet-specific failures
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+            throw new Error('Invalid date');
+        }
+        if (latitude < -90 || latitude > 90) {
+            throw new Error(`Invalid latitude: ${latitude} (must be -90 to 90)`);
+        }
+        if (!Number.isFinite(longitude)) {
+            throw new Error('Invalid longitude: must be a finite number');
+        }
+        if (!Number.isFinite(altitude)) {
+            throw new Error('Invalid altitude: must be a finite number');
+        }
+        const jd = this.ephem.dateToJulianDay(date);
+        const results = [];
+        // Calculate for Sun through Pluto (0-9)
+        // Only catch planet-specific computation failures (e.g., circumpolar edge cases)
+        for (let planetId = 0; planetId <= 9; planetId++) {
+            try {
+                const riseSet = this.calculateRiseSet(jd, planetId, latitude, longitude, altitude);
+                results.push(riseSet);
+            }
+            catch (error) {
+                // Planet-specific calculation failure - log and continue with other planets
+                logger.warn(`Failed to calculate rise/set for planet ${planetId}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get Sun rise/set times for the current instant
+     *
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Rise/set times for the Sun
+     * @throws Error if ephemeris not initialized or invalid inputs
+     *
+     * @remarks
+     * Searches for the next sunrise/sunset after the current instant.
+     * If called in the afternoon, sunrise will be tomorrow.
+     * For events on a specific civil date, use calculateRiseSet with midnight JD.
+     */
+    async getSunRiseSet(latitude, longitude, altitude = 0) {
+        // Validate inputs before calculation
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        if (latitude < -90 || latitude > 90) {
+            throw new Error(`Invalid latitude: ${latitude} (must be -90 to 90)`);
+        }
+        if (!Number.isFinite(longitude)) {
+            throw new Error('Invalid longitude: must be a finite number');
+        }
+        if (!Number.isFinite(altitude)) {
+            throw new Error('Invalid altitude: must be a finite number');
+        }
+        const now = new Date();
+        const jd = this.ephem.dateToJulianDay(now);
+        return this.calculateRiseSet(jd, 0, latitude, longitude, altitude); // Sun is planet ID 0
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+import { NatalChart } from './types.js';
+import { EphemerisCalculator } from './ephemeris.js';
+export declare class ChartStorage {
+    private ephem;
+    constructor(ephem: EphemerisCalculator);
+    saveNatalChart(chart: NatalChart): Promise<void>;
+    loadNatalChart(): Promise<NatalChart | null>;
+    private calculateNatalPlanets;
+    hasNatalChart(): Promise<boolean>;
+}

package/dist/storage.js

@@ -0,0 +1,40 @@
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { PLANETS } from './types.js';
+// Get project root (dist/ -> project/)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+const STORAGE_PATH = process.env.NATAL_CHART_PATH || join(projectRoot, 'natal-chart.json');
+export class ChartStorage {
+    ephem;
+    constructor(ephem) {
+        this.ephem = ephem;
+    }
+    async saveNatalChart(chart) {
+        const chartWithPlanets = await this.calculateNatalPlanets(chart);
+        await writeFile(STORAGE_PATH, JSON.stringify(chartWithPlanets, null, 2));
+    }
+    async loadNatalChart() {
+        if (!existsSync(STORAGE_PATH)) {
+            return null;
+        }
+        const data = await readFile(STORAGE_PATH, 'utf-8');
+        return JSON.parse(data);
+    }
+    async calculateNatalPlanets(chart) {
+        const { year, month, day, hour, minute, second = 0 } = chart.birthDate;
+        const birthDate = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+        const jd = this.ephem.dateToJulianDay(birthDate);
+        const planetIds = Object.values(PLANETS);
+        const planets = this.ephem.getAllPlanets(jd, planetIds);
+        return {
+            ...chart,
+            planets
+        };
+    }
+    async hasNatalChart() {
+        return existsSync(STORAGE_PATH);
+    }
+}

package/dist/time-utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Time conversion utilities for astrology calculations
+ *
+ * Provides centralized time handling to ensure consistent conversion
+ * between local time and UTC across the entire codebase.
+ *
+ * DST Policy:
+ * - Nonexistent times (spring-forward gap): Use 'compatible' by default,
+ *   which shifts forward. Use 'reject' for birth times to surface ambiguity.
+ * - Ambiguous times (fall-back overlap): Use 'compatible' by default,
+ *   which prefers the earlier occurrence. Use 'reject' for birth times.
+ * - Offset sign convention: Positive = east of UTC, Negative = west of UTC
+ *   (e.g., America/Los_Angeles = -480 winter, -420 summer; Asia/Tokyo = 540)
+ */
+export interface LocalDateTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second?: number;
+}
+export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+/**
+ * Convert local time to UTC using timezone information
+ *
+ * @param local - Local date/time components
+ * @param timezone - IANA timezone string (e.g., 'America/New_York')
+ * @param disambiguation - How to handle DST ambiguity ('compatible' default, 'reject' for birth times)
+ * @returns UTC Date object
+ * @throws Error if timezone is invalid or time is ambiguous/nonexistent with 'reject'
+ */
+export declare function localToUTC(local: LocalDateTime, timezone: string, disambiguation?: Disambiguation): Date;
+/**
+ * Convert UTC time to local time in specified timezone
+ *
+ * @param utc - UTC Date object
+ * @param timezone - IANA timezone string
+ * @returns Local date/time components
+ */
+export declare function utcToLocal(utc: Date, timezone: string): LocalDateTime;
+/**
+ * Validate if a timezone string is valid
+ *
+ * @param timezone - Timezone string to validate
+ * @returns true if valid IANA timezone or UTC, false otherwise
+ */
+export declare function isValidTimezone(timezone: string): boolean;
+/**
+ * Get timezone offset in minutes for a specific date
+ * Handles DST transitions correctly
+ *
+ * @param date - Date to get offset for
+ * @param timezone - IANA timezone string
+ * @returns Offset in minutes (positive = east of UTC, negative = west of UTC)
+ *          Examples: America/Los_Angeles winter = -480, summer = -420; Asia/Tokyo = 540
+ */
+export declare function getTimezoneOffset(date: Date, timezone: string): number;
+/**
+ * Add calendar days to a local date in a specific timezone
+ * Properly handles month/year rollovers and DST transitions
+ *
+ * @param local - Starting local date/time
+ * @param timezone - IANA timezone string
+ * @param days - Number of days to add (can be negative)
+ * @returns UTC Date representing the new local date/time
+ */
+export declare function addLocalDays(local: LocalDateTime, timezone: string, days: number): Date;

package/dist/time-utils.js

@@ -0,0 +1,136 @@
+/**
+ * Time conversion utilities for astrology calculations
+ *
+ * Provides centralized time handling to ensure consistent conversion
+ * between local time and UTC across the entire codebase.
+ *
+ * DST Policy:
+ * - Nonexistent times (spring-forward gap): Use 'compatible' by default,
+ *   which shifts forward. Use 'reject' for birth times to surface ambiguity.
+ * - Ambiguous times (fall-back overlap): Use 'compatible' by default,
+ *   which prefers the earlier occurrence. Use 'reject' for birth times.
+ * - Offset sign convention: Positive = east of UTC, Negative = west of UTC
+ *   (e.g., America/Los_Angeles = -480 winter, -420 summer; Asia/Tokyo = 540)
+ */
+import { Temporal } from '@js-temporal/polyfill';
+/**
+ * Convert local time to UTC using timezone information
+ *
+ * @param local - Local date/time components
+ * @param timezone - IANA timezone string (e.g., 'America/New_York')
+ * @param disambiguation - How to handle DST ambiguity ('compatible' default, 'reject' for birth times)
+ * @returns UTC Date object
+ * @throws Error if timezone is invalid or time is ambiguous/nonexistent with 'reject'
+ */
+export function localToUTC(local, timezone, disambiguation = 'compatible') {
+    // Validate timezone first
+    if (!isValidTimezone(timezone)) {
+        throw new Error(`Invalid timezone: ${timezone}`);
+    }
+    // Build Temporal.PlainDateTime from LocalDateTime
+    const plainDateTime = Temporal.PlainDateTime.from({
+        year: local.year,
+        month: local.month,
+        day: local.day,
+        hour: local.hour,
+        minute: local.minute,
+        second: local.second ?? 0,
+    });
+    // Convert to ZonedDateTime in the target timezone
+    const zonedDateTime = plainDateTime.toZonedDateTime(timezone, { disambiguation });
+    // Return as Date
+    return new Date(zonedDateTime.epochMilliseconds);
+}
+/**
+ * Convert UTC time to local time in specified timezone
+ *
+ * @param utc - UTC Date object
+ * @param timezone - IANA timezone string
+ * @returns Local date/time components
+ */
+export function utcToLocal(utc, timezone) {
+    // Convert Date to Temporal.Instant
+    const instant = Temporal.Instant.fromEpochMilliseconds(utc.getTime());
+    // Convert to ZonedDateTime in target timezone
+    const zonedDateTime = instant.toZonedDateTimeISO(timezone);
+    // Return numeric components
+    return {
+        year: zonedDateTime.year,
+        month: zonedDateTime.month,
+        day: zonedDateTime.day,
+        hour: zonedDateTime.hour,
+        minute: zonedDateTime.minute,
+        second: zonedDateTime.second,
+    };
+}
+/**
+ * Validate if a timezone string is valid
+ *
+ * @param timezone - Timezone string to validate
+ * @returns true if valid IANA timezone or UTC, false otherwise
+ */
+export function isValidTimezone(timezone) {
+    if (!timezone || timezone.length === 0) {
+        return false;
+    }
+    try {
+        // Validate by attempting to create a ZonedDateTime
+        // This accepts any valid IANA timezone identifier
+        const testDate = Temporal.PlainDateTime.from({
+            year: 2000,
+            month: 1,
+            day: 1,
+            hour: 0,
+            minute: 0,
+        });
+        testDate.toZonedDateTime(timezone);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get timezone offset in minutes for a specific date
+ * Handles DST transitions correctly
+ *
+ * @param date - Date to get offset for
+ * @param timezone - IANA timezone string
+ * @returns Offset in minutes (positive = east of UTC, negative = west of UTC)
+ *          Examples: America/Los_Angeles winter = -480, summer = -420; Asia/Tokyo = 540
+ */
+export function getTimezoneOffset(date, timezone) {
+    // Convert Date to Temporal.Instant
+    const instant = Temporal.Instant.fromEpochMilliseconds(date.getTime());
+    // Convert to ZonedDateTime in target timezone
+    const zonedDateTime = instant.toZonedDateTimeISO(timezone);
+    // Get offset from the ZonedDateTime itself
+    // offsetNanoseconds is positive for east, negative for west
+    const offsetMinutes = zonedDateTime.offsetNanoseconds / (1000 * 1000 * 1000 * 60);
+    return offsetMinutes;
+}
+/**
+ * Add calendar days to a local date in a specific timezone
+ * Properly handles month/year rollovers and DST transitions
+ *
+ * @param local - Starting local date/time
+ * @param timezone - IANA timezone string
+ * @param days - Number of days to add (can be negative)
+ * @returns UTC Date representing the new local date/time
+ */
+export function addLocalDays(local, timezone, days) {
+    // Convert to Temporal for proper calendar math
+    const plainDateTime = Temporal.PlainDateTime.from({
+        year: local.year,
+        month: local.month,
+        day: local.day,
+        hour: local.hour,
+        minute: local.minute,
+        second: local.second ?? 0,
+    });
+    // Add days using Temporal's calendar-aware addition
+    const newPlainDateTime = plainDateTime.add({ days });
+    // Convert back to UTC via the timezone
+    const zonedDateTime = newPlainDateTime.toZonedDateTime(timezone);
+    return new Date(zonedDateTime.epochMilliseconds);
+}

package/dist/tool-registry.d.ts

@@ -0,0 +1,35 @@
+import type { AstroService } from './astro-service.js';
+import type { NatalChart } from './types.js';
+type ToolContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+export type ToolExecutionResult = {
+    kind: 'state';
+    data: Record<string, unknown>;
+    text: string;
+    natalChart?: NatalChart;
+} | {
+    kind: 'content';
+    content: ToolContent[];
+};
+export interface ToolExecutionContext {
+    service: AstroService;
+    natalChart: NatalChart | null;
+}
+type ToolArgs = Record<string, unknown>;
+export interface ToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    requiresNatalChart: boolean;
+    execute: (ctx: ToolExecutionContext, args: ToolArgs) => Promise<ToolExecutionResult> | ToolExecutionResult;
+}
+export declare const MCP_TOOL_SPECS: ToolSpec[];
+export declare function createToolSpecIndex(specs?: ToolSpec[]): Map<string, ToolSpec>;
+export declare function getToolSpec(name: string): ToolSpec | undefined;
+export {};