ether-to-astro 1.2.0 → 1.3.0

package/dist/tool-registry.js

@@ -175,7 +175,7 @@ export const MCP_TOOL_SPECS = [
                 },
                 include_mundane: {
                     type: 'boolean',
-                    description: 'Include current planetary positions (not transits to natal chart). Defaults to false.',
+                    description: 'Include deterministic mundane baseline data for the requested window. Output includes planetary positions, transit-to-transit mundane aspects, and non-narrative weather grouping metadata; forecast windows also include per-day mundane.days entries. Defaults to false.',
                 },
                 days_ahead: {
                     type: 'number',

package/docs/product/architecture-boundaries.md

@@ -195,6 +195,14 @@ Do not add a new MCP primitive when:
 
 Based on the current product direction:
 
+### Shared behavior boundary
+
+- `src/astro-service.ts` remains the shared CLI/MCP behavior boundary.
+- `AstroService` should stay a thin facade and orchestration layer.
+- Shared implementation should usually live in the internal domain modules under `src/astro-service/`.
+- New shared behavior should be added to the appropriate extracted service first, not piled back into the facade file.
+- Public types may be re-exported from `src/astro-service.ts`, but domain logic should stay in the internal service modules unless there is a clear contract reason not to.
+
 ### Strong candidates for MCP
 
 - range-aware transit forecast data

package/docs/releases/1.3.0.md

@@ -0,0 +1,51 @@
+# ether-to-astro v1.3.0
+
+Suggested release type: `minor`
+
+This release builds on `1.2.0` with a friendlier binary name, a cleaner internal service architecture, stronger validation/property coverage, and a small but explicit rising-sign payload correction. It also finishes the public contract alignment for the already-shipped mundane aspect and weather output.
+
+## 1.3.0 (2026-03-29)
+
+### New feature
+
+- add `ether-to-astro` as a first-class CLI binary alias alongside `e2a` and `e2a-mcp`
+- add a property-test lane via `npm run test:property` for generated invariants across time utilities, houses, transits, electional context, service-level transits, and rising-sign windows
+- expand validation harness coverage to include service-layer electional context, rising-sign windows, and service transit serialization
+
+### Bug fix
+
+- ⚠️ Breaking change: `getRisingSignWindows` structured window payloads now emit `durationMs` instead of `durationMinutes`
+- use raw Sun altitude for electional sect classification so slightly negative values that round to `0.00` are still classified correctly as night charts
+- keep rising-sign exact-vs-approximate precision checks active even when approximate windows only match a coarse subsequence of exact windows
+- align the rising-sign property helper with the validation comparator so the generated invariant measures the first real departure from the left sign instead of assuming a direct sign-to-sign jump
+
+### Documentation Changes
+
+- update `get_transits` contract wording so `include_mundane` describes the shipped mundane positions, aspects, weather metadata, and forecast `mundane.days[]` behavior
+- refresh README transit docs so public docs no longer imply range-aware mundane output is still tracked separately
+
+### ⚙️ Chore
+
+- extract transit, electional, rising-sign, natal, sky, and chart-output workflows into focused `src/astro-service/*` modules while preserving the shared `AstroService` surface
+- finish migration to shared service types and reorganized test seams so service behavior is easier to validate without surface drift
+- add service-layer validation coverage and a new `npm run test:property` lane for generated invariant checks across core astro and service behavior
+- add regression coverage for the rising-sign precision no-op scenario and contract coverage for mundane schema wording drift
+
+## Upgrade notes
+
+- 🚨 Breaking change: `getRisingSignWindows` now emits `durationMs` for each window object
+- ❌ `durationMinutes` is no longer present in the structured rising-sign payload
+- 🔧 if you consume rising-sign output programmatically, update any client code that reads or displays the old minute-based field
+- 🧭 if you consume `include_mundane` programmatically, the docs/schema now reflect the richer behavior already shipping on `main`
+
+## Included PRs
+
+- #44 fix electional sect classification to use raw Sun altitude
+- #46 extract transit workflow into focused service layer modules
+- #49 add `ether-to-astro` binary alias
+- #50 extract electional and rising-sign workflows
+- #51 extract natal, sky, and chart-output workflows
+- #52 finish service docs/types/test migration
+- #53 add service-layer validation coverage and enforce the `durationMs` contract
+- #54 add property-based invariant coverage
+- #55 keep rising-sign precision validation active and align mundane contract docs/schema with shipped behavior

package/docs/releases/README.md

@@ -0,0 +1,17 @@
+# Releases
+
+Release notes for `ether-to-astro` live in this directory.
+
+Conventions:
+
+- Use one draft file per pending release, named like `1.2.0-draft.md`.
+- Call out breaking API or payload changes explicitly in an `Upgrade notes` section.
+- If a breaking change is kept despite early release-stage flexibility, say so plainly instead of hiding it in feature bullets.
+
+Current draft:
+
+- [v1.2.0 draft](/Users/salted/Code/astro-mcp/docs/releases/1.2.0-draft.md)
+
+Released notes:
+
+- [v1.3.0 notes](/Users/salted/Code/astro-mcp/docs/releases/1.3.0.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ether-to-astro",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local-first astrology toolkit with a unified e2a binary for CLI and MCP workflows, plus an e2a-mcp compatibility alias.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
     "node": ">=22"
   },
   "bin": {
+    "ether-to-astro": "dist/loader.js",
     "e2a": "dist/loader.js",
     "e2a-mcp": "dist/mcp-alias.js"
   },
@@ -19,6 +20,7 @@
     "start:cli": "node dist/loader.js",
     "postinstall": "node scripts/download-ephemeris.js",
     "test": "vitest tests/unit",
+    "test:property": "vitest run tests/property",
     "validate:astro": "vitest run tests/validation",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run tests/unit --coverage",
@@ -56,6 +58,7 @@
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.2",
     "@vitest/ui": "^4.1.2",
+    "fast-check": "^4.6.0",
     "happy-dom": "^20.8.9",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",

package/src/astro-service/chart-output-service.ts

@@ -0,0 +1,155 @@
+import type { ChartRenderer } from '../charts.js';
+import { getDefaultTheme } from '../constants.js';
+import { formatDateOnly } from '../formatter.js';
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import type { NatalChart } from '../types.js';
+import { parseDateOnlyInput } from './date-input.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 class ChartOutputService {
+  private readonly chartRenderer: ChartRenderer;
+  private readonly now: () => Date;
+  private readonly writeFile: (
+    path: string,
+    data: string | Buffer,
+    encoding?: BufferEncoding
+  ) => Promise<void>;
+
+  constructor(deps: ChartOutputServiceDependencies) {
+    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: NatalChart,
+    input: GenerateChartInput = {}
+  ): Promise<ChartServiceResult> {
+    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 as string, 'utf-8');
+      } else {
+        await this.writeFile(outputPath, chart as Buffer);
+      }
+      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 as string,
+      };
+    }
+
+    return {
+      format,
+      text: `Natal Chart for ${natalChart.name} (${theme} theme, ${format.toUpperCase()} format):`,
+      image: {
+        data: (chart as Buffer).toString('base64'),
+        mimeType: format === 'png' ? 'image/png' : 'image/webp',
+      },
+    };
+  }
+
+  /**
+   * Generate a transit chart image or SVG for a target date.
+   */
+  async generateTransitChart(
+    natalChart: NatalChart,
+    input: GenerateTransitChartInput = {}
+  ): Promise<ChartServiceResult> {
+    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 as string, 'utf-8');
+      } else {
+        await this.writeFile(outputPath, chart as Buffer);
+      }
+      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 as string,
+      };
+    }
+
+    return {
+      format,
+      text: `Transit Chart for ${natalChart.name} (${dateLabel}, ${theme} theme, ${format.toUpperCase()} format):`,
+      image: {
+        data: (chart as Buffer).toString('base64'),
+        mimeType: format === 'png' ? 'image/png' : 'image/webp',
+      },
+    };
+  }
+
+  /**
+   * Resolve the local-noon transit anchor when the caller omits a date.
+   */
+  private resolveTransitTargetDate(natalChart: NatalChart, dateStr?: string): Date {
+    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/src/astro-service/date-input.ts

@@ -0,0 +1,40 @@
+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: string): {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+} {
+  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 };
+}