ether-to-astro 1.2.0 → 1.3.0

package/README.md

@@ -41,6 +41,12 @@ Then restart your MCP client and call `set_natal_chart`.
 
 Run the CLI directly with `npx`:
 
+```bash
+npx --yes ether-to-astro --help
+```
+
+Or:
+
 ```bash
 npx --yes --package=ether-to-astro e2a --help
 ```
@@ -87,6 +93,8 @@ You can ask your AI agent about:
 
 ### Transits
 - **Daily mundane positions** - Current planetary positions
+- **Mundane transit-to-transit aspects** - Deterministic aspect signals between transiting bodies
+- **Mundane weather metadata** - Deterministic supportive/challenging grouping references (non-narrative)
 - **Moon transits** - Fast-moving Moon aspects to natal planets
 - **Personal planet transits** - Sun, Mercury, Venus, Mars aspects to natal chart
 - **Outer planet transits** - Jupiter, Saturn, Uranus, Neptune, Pluto aspects
@@ -158,7 +166,7 @@ npm install
 ## Package Names
 
 - Package: `ether-to-astro`
-- CLI command: `e2a`
+- CLI command aliases: `ether-to-astro`, `e2a`
 - Canonical MCP command: `e2a --mcp`
 - Compatibility MCP alias: `e2a-mcp`
 
@@ -194,8 +202,10 @@ This design is **MCP-compliant** for stdio transport and ensures complete isolat
 
 `e2a` is JSON-first for agent usage and supports `--pretty` for human-readable output.
 
-`npx` usage note: this package is named `ether-to-astro`, so invoke bins with `--package`.
-`npx e2a` will not work by itself because npm resolves package names first.
+`npx` usage note:
+- `npx ether-to-astro ...` works directly (package-name bin alias).
+- `npx e2a ...` does **not** work by itself because npm resolves package names first.
+- `npx --package=ether-to-astro e2a ...` remains supported.
 
 Examples:
 
@@ -294,8 +304,8 @@ Ask your AI agent:
   - `forecast`: day-grouped transit output across the selected date window
   - if `mode` is omitted, legacy behavior is preserved: `days_ahead=0` resolves to `snapshot`, and `days_ahead>0` resolves to `best_hit`
   - each transit now includes additive placement metadata for both sides: sign, degree, and house
-
-In this release, `include_mundane` remains anchored to the forecast start date even when `mode=forecast`. Range-aware mundane output is tracked separately.
+  - with `include_mundane=true`, output includes deterministic mundane positions plus `mundane.aspects` and non-narrative `mundane.weather` grouping metadata
+  - when `include_mundane=true` and `mode=forecast`, output includes `mundane.days[]` with per-day grouped mundane aspects/weather
 
 ### Electional
 - `get_electional_context` - Stateless electional context for a local date, time, and location. Returns deterministic ascendant, sect/day-night classification, Moon phase, applying aspects, and optional ASC-ruler basics without requiring a natal chart.

package/dist/astro-service/chart-output-service.d.ts

@@ -0,0 +1,44 @@
+import type { ChartRenderer } from '../charts.js';
+import type { NatalChart } from '../types.js';
+import type { GenerateChartInput, GenerateTransitChartInput } from './service-types.js';
+interface ChartServiceResult {
+    format: 'svg' | 'png' | 'webp';
+    outputPath?: string;
+    text: string;
+    svg?: string;
+    image?: {
+        data: string;
+        mimeType: string;
+    };
+}
+interface ChartOutputServiceDependencies {
+    chartRenderer: ChartRenderer;
+    now: () => Date;
+    writeFile: (path: string, data: string | Buffer, encoding?: BufferEncoding) => Promise<void>;
+}
+/**
+ * Internal chart rendering/output workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns theme defaults, target-date resolution, and inline-vs-file
+ * output serialization for natal and transit chart rendering.
+ */
+export declare class ChartOutputService {
+    private readonly chartRenderer;
+    private readonly now;
+    private readonly writeFile;
+    constructor(deps: ChartOutputServiceDependencies);
+    /**
+     * Generate a natal chart image or SVG for the current chart.
+     */
+    generateNatalChart(natalChart: NatalChart, input?: GenerateChartInput): Promise<ChartServiceResult>;
+    /**
+     * Generate a transit chart image or SVG for a target date.
+     */
+    generateTransitChart(natalChart: NatalChart, input?: GenerateTransitChartInput): Promise<ChartServiceResult>;
+    /**
+     * Resolve the local-noon transit anchor when the caller omits a date.
+     */
+    private resolveTransitTargetDate;
+}
+export {};

package/dist/astro-service/chart-output-service.js

@@ -0,0 +1,110 @@
+import { getDefaultTheme } from '../constants.js';
+import { formatDateOnly } from '../formatter.js';
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import { parseDateOnlyInput } from './date-input.js';
+/**
+ * Internal chart rendering/output workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns theme defaults, target-date resolution, and inline-vs-file
+ * output serialization for natal and transit chart rendering.
+ */
+export class ChartOutputService {
+    chartRenderer;
+    now;
+    writeFile;
+    constructor(deps) {
+        this.chartRenderer = deps.chartRenderer;
+        this.now = deps.now;
+        this.writeFile = deps.writeFile;
+    }
+    /**
+     * Generate a natal chart image or SVG for the current chart.
+     */
+    async generateNatalChart(natalChart, input = {}) {
+        const theme = input.theme || getDefaultTheme(natalChart.location.timezone);
+        const format = input.format || 'svg';
+        const outputPath = input.output_path;
+        const chart = await this.chartRenderer.generateNatalChart(natalChart, theme, format);
+        if (outputPath) {
+            if (format === 'svg') {
+                await this.writeFile(outputPath, chart, 'utf-8');
+            }
+            else {
+                await this.writeFile(outputPath, chart);
+            }
+            return {
+                format,
+                outputPath,
+                text: `Natal Chart for ${natalChart.name} saved to: ${outputPath}`,
+            };
+        }
+        if (format === 'svg') {
+            return {
+                format,
+                text: `Natal Chart for ${natalChart.name}:`,
+                svg: chart,
+            };
+        }
+        return {
+            format,
+            text: `Natal Chart for ${natalChart.name} (${theme} theme, ${format.toUpperCase()} format):`,
+            image: {
+                data: chart.toString('base64'),
+                mimeType: format === 'png' ? 'image/png' : 'image/webp',
+            },
+        };
+    }
+    /**
+     * Generate a transit chart image or SVG for a target date.
+     */
+    async generateTransitChart(natalChart, input = {}) {
+        const theme = input.theme ?? getDefaultTheme(natalChart.location.timezone);
+        const format = input.format ?? 'svg';
+        const targetDate = this.resolveTransitTargetDate(natalChart, input.date);
+        const outputPath = input.output_path;
+        const chart = await this.chartRenderer.generateTransitChart(natalChart, targetDate, theme, format);
+        const dateLabel = formatDateOnly(targetDate, natalChart.location.timezone);
+        if (outputPath) {
+            if (format === 'svg') {
+                await this.writeFile(outputPath, chart, 'utf-8');
+            }
+            else {
+                await this.writeFile(outputPath, chart);
+            }
+            return {
+                format,
+                outputPath,
+                text: `Transit Chart for ${natalChart.name} (${dateLabel}) saved to ${outputPath}`,
+            };
+        }
+        if (format === 'svg') {
+            return {
+                format,
+                text: `Transit Chart for ${natalChart.name} (${dateLabel})`,
+                svg: chart,
+            };
+        }
+        return {
+            format,
+            text: `Transit Chart for ${natalChart.name} (${dateLabel}, ${theme} theme, ${format.toUpperCase()} format):`,
+            image: {
+                data: chart.toString('base64'),
+                mimeType: format === 'png' ? 'image/png' : 'image/webp',
+            },
+        };
+    }
+    /**
+     * Resolve the local-noon transit anchor when the caller omits a date.
+     */
+    resolveTransitTargetDate(natalChart, dateStr) {
+        if (dateStr) {
+            const parsed = parseDateOnlyInput(dateStr);
+            return localToUTC(parsed, natalChart.location.timezone);
+        }
+        const now = this.now();
+        const localNow = utcToLocal(now, natalChart.location.timezone);
+        const localNoon = { ...localNow, hour: 12, minute: 0, second: 0 };
+        return localToUTC(localNoon, natalChart.location.timezone);
+    }
+}

package/dist/astro-service/date-input.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse a date-only input into local noon components.
+ *
+ * @remarks
+ * The service treats date-only transit requests as local-noon lookups so the
+ * requested calendar day remains stable across timezone conversions.
+ */
+export declare function parseDateOnlyInput(dateStr: string): {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+};

package/dist/astro-service/date-input.js

@@ -0,0 +1,30 @@
+import { Temporal } from '@js-temporal/polyfill';
+/**
+ * Parse a date-only input into local noon components.
+ *
+ * @remarks
+ * The service treats date-only transit requests as local-noon lookups so the
+ * requested calendar day remains stable across timezone conversions.
+ */
+export function parseDateOnlyInput(dateStr) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
+    if (!match) {
+        throw new Error(`Invalid date format: expected YYYY-MM-DD, got "${dateStr}"`);
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (month < 1 || month > 12) {
+        throw new Error(`Invalid month: ${month} (must be 1-12)`);
+    }
+    if (day < 1 || day > 31) {
+        throw new Error(`Invalid day: ${day} (must be 1-31)`);
+    }
+    try {
+        Temporal.PlainDate.from({ year, month, day });
+    }
+    catch {
+        throw new Error(`Invalid calendar date: ${dateStr}`);
+    }
+    return { year, month, day, hour: 12, minute: 0 };
+}

package/dist/astro-service/electional-service.d.ts

@@ -0,0 +1,45 @@
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import type { GetElectionalContextInput, ServiceResult } from './service-types.js';
+interface ElectionalServiceDependencies {
+    ephem: EphemerisCalculator;
+    houseCalc: HouseCalculator;
+}
+/**
+ * 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 declare class ElectionalService {
+    private readonly ephem;
+    private readonly houseCalc;
+    constructor(deps: ElectionalServiceDependencies);
+    /**
+     * Produce deterministic electional context for a single local instant.
+     */
+    getElectionalContext(input: GetElectionalContextInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Return only currently applying aspects inside the requested orb.
+     */
+    private getElectionalApplyingAspects;
+    /**
+     * Determine whether a near-aspect is applying instead of separating.
+     */
+    private isElectionalAspectApplying;
+    /**
+     * Compute the signed shortest angular distance in degrees.
+     */
+    private getSignedAngularDifference;
+    /**
+     * Bucket a Sun-Moon phase angle into the service's coarse phase names.
+     */
+    private getElectionalPhaseName;
+    /**
+     * Return the traditional ruler used for the ascendant sign summary.
+     */
+    private getTraditionalSignRuler;
+}
+export {};

package/dist/astro-service/electional-service.js

@@ -0,0 +1,305 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { localToUTC } from '../time-utils.js';
+import { ASPECTS, PLANETS, ZODIAC_SIGNS, } from '../types.js';
+import { parseDateOnlyInput } from './date-input.js';
+import { normalizeLongitude } from './shared.js';
+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 = ['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 {
+    ephem;
+    houseCalc;
+    constructor(deps) {
+        this.ephem = deps.ephem;
+        this.houseCalc = deps.houseCalc;
+    }
+    /**
+     * Produce deterministic electional context for a single local instant.
+     */
+    getElectionalContext(input) {
+        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;
+        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 = [];
+        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 = {
+            input: {
+                date: input.date,
+                time: input.time,
+                timezone: input.timezone,
+                latitude: input.latitude,
+                longitude: input.longitude,
+                house_system: houses.system,
+                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,
+            text: humanText.join('\n'),
+        };
+    }
+    /**
+     * Return only currently applying aspects inside the requested orb.
+     */
+    getElectionalApplyingAspects(positions, orbDegrees) {
+        const aspects = [];
+        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.
+     */
+    isElectionalAspectApplying(from, to, aspectAngle) {
+        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.
+     */
+    getSignedAngularDifference(fromLongitude, toLongitude) {
+        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.
+     */
+    getElectionalPhaseName(phaseAngle) {
+        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.
+     */
+    getTraditionalSignRuler(sign) {
+        const signRulers = {
+            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) {
+    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/dist/astro-service/natal-service.d.ts

@@ -0,0 +1,41 @@
+import type { McpStartupDefaults } from '../entrypoint.js';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import { type NatalChart } from '../types.js';
+import type { GetHousesInput, ServiceResult, SetNatalChartInput } from './service-types.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 declare class NatalService {
+    private readonly ephem;
+    private readonly houseCalc;
+    private readonly mcpStartupDefaults;
+    private readonly isInitialized;
+    constructor(deps: NatalServiceDependencies);
+    /**
+     * Build and cache the shared natal chart payload used by later workflows.
+     */
+    setNatalChart(input: SetNatalChartInput): ServiceResult<Record<string, unknown>> & {
+        chart: NatalChart;
+    };
+    /**
+     * Calculate house cusps and angles for a natal chart.
+     */
+    getHouses(natalChart: NatalChart, input?: GetHousesInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Summarize process-local server state and configured startup defaults.
+     */
+    getServerStatus(natalChart: NatalChart | null): ServiceResult<Record<string, unknown>>;
+}
+export {};