ether-to-astro 1.0.2 → 1.2.0

package/dist/cli.js

@@ -308,6 +308,35 @@ export async function runCli(argv, io = {
         const result = await spec.execute({ service, natalChart: null }, { timezone });
         emitExecution(io, result, options.pretty ?? false);
     });
+    program
+        .command('get-electional-context')
+        .description(mustTool('get_electional_context').description)
+        .requiredOption('--date <yyyy-mm-dd>', toolSchemaProperty('get_electional_context', 'date').description ?? 'Target local date')
+        .requiredOption('--time <hh:mm[:ss]>', toolSchemaProperty('get_electional_context', 'time').description ?? 'Target local time')
+        .requiredOption('--timezone <tz>', toolSchemaProperty('get_electional_context', 'timezone').description ?? 'Timezone')
+        .requiredOption('--latitude <number>', toolSchemaProperty('get_electional_context', 'latitude').description ?? 'Latitude')
+        .requiredOption('--longitude <number>', toolSchemaProperty('get_electional_context', 'longitude').description ?? 'Longitude')
+        .addOption(new Option('--house-system <system>', toolSchemaProperty('get_electional_context', 'house_system').description ?? 'House system').choices(['P', 'K', 'W', 'R']))
+        .option('--include-ruler-basics', toolSchemaProperty('get_electional_context', 'include_ruler_basics').description ??
+        'Include ascendant-ruler basics')
+        .option('--no-planetary-applications', 'Exclude applying major aspects from the electional context response')
+        .option('--orb-degrees <number>', toolSchemaProperty('get_electional_context', 'orb_degrees').description ?? 'Aspect orb')
+        .option('--pretty', 'Human-readable output instead of JSON')
+        .action(async (options) => {
+        const spec = mustTool('get_electional_context');
+        const result = await spec.execute({ service, natalChart: null }, {
+            date: options.date,
+            time: options.time,
+            timezone: options.timezone,
+            latitude: toNumber(options.latitude, 'latitude'),
+            longitude: toNumber(options.longitude, 'longitude'),
+            house_system: options.houseSystem,
+            include_ruler_basics: options.includeRulerBasics,
+            include_planetary_applications: options.planetaryApplications,
+            orb_degrees: options.orbDegrees == null ? undefined : toNumber(options.orbDegrees, 'orb-degrees'),
+        });
+        emitExecution(io, result, options.pretty ?? false);
+    });
     const profiles = program
         .command('profiles')
         .description('Inspect and validate CLI profile files');
@@ -378,6 +407,7 @@ export async function runCli(argv, io = {
         .option('--include-mundane', toolSchemaProperty('get_transits', 'include_mundane').description ??
         'Include mundane positions')
         .option('--days-ahead <number>', toolSchemaProperty('get_transits', 'days_ahead').description ?? 'Days ahead')
+        .addOption(new Option('--mode <mode>', toolSchemaProperty('get_transits', 'mode').description ?? 'Transit mode').choices(['snapshot', 'best_hit', 'forecast']))
         .option('--max-orb <number>', toolSchemaProperty('get_transits', 'max_orb').description ?? 'Max orb')
         .option('--exact-only', toolSchemaProperty('get_transits', 'exact_only').description ?? 'Exact only')
         .option('--applying-only', toolSchemaProperty('get_transits', 'applying_only').description ?? 'Applying only')
@@ -392,6 +422,7 @@ export async function runCli(argv, io = {
                 categories,
                 include_mundane: options.includeMundane,
                 days_ahead: options.daysAhead == null ? undefined : toNumber(options.daysAhead, 'days-ahead'),
+                mode: options.mode,
                 max_orb: options.maxOrb == null ? undefined : toNumber(options.maxOrb, 'max-orb'),
                 exact_only: options.exactOnly,
                 applying_only: options.applyingOnly,

package/dist/entrypoint.d.ts

@@ -0,0 +1,13 @@
+import type { HouseSystem } from './types.js';
+export interface McpStartupDefaults {
+    preferredTimezone?: string;
+    preferredHouseStyle?: HouseSystem;
+    weekdayLabels?: boolean;
+}
+export interface EntrypointResolution {
+    mode: 'cli' | 'mcp';
+    cliArgv: string[];
+    mcpHelpRequested: boolean;
+    mcpStartupDefaults: Readonly<McpStartupDefaults>;
+}
+export declare function resolveEntrypoint(argv: string[], invokedPath?: string): EntrypointResolution;

package/dist/entrypoint.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { isValidTimezone } from './time-utils.js';
+const VALID_HOUSE_STYLES = new Set(['P', 'W', 'K', 'E']);
+function readOptionValue(argv, index, flag) {
+    const current = argv[index];
+    const prefix = `${flag}=`;
+    if (current.startsWith(prefix)) {
+        return {
+            value: current.slice(prefix.length),
+            nextIndex: index,
+        };
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return {
+        value: next,
+        nextIndex: index + 1,
+    };
+}
+export function resolveEntrypoint(argv, invokedPath = process.argv[1] ?? '') {
+    let mode = path.basename(invokedPath).startsWith('e2a-mcp') ? 'mcp' : 'cli';
+    const cliArgv = [];
+    const defaults = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--mcp') {
+            mode = 'mcp';
+            continue;
+        }
+        if (arg === '--weekday-labels') {
+            defaults.weekdayLabels = true;
+            continue;
+        }
+        if (arg === '--no-weekday-labels') {
+            defaults.weekdayLabels = false;
+            continue;
+        }
+        if (arg === '--preferred-tz' || arg.startsWith('--preferred-tz=')) {
+            const { value, nextIndex } = readOptionValue(argv, i, '--preferred-tz');
+            defaults.preferredTimezone = value;
+            i = nextIndex;
+            continue;
+        }
+        if (arg === '--preferred-house-style' || arg.startsWith('--preferred-house-style=')) {
+            const { value, nextIndex } = readOptionValue(argv, i, '--preferred-house-style');
+            defaults.preferredHouseStyle = value;
+            i = nextIndex;
+            continue;
+        }
+        cliArgv.push(arg);
+    }
+    const usedMcpOnlyFlag = defaults.preferredTimezone !== undefined ||
+        defaults.preferredHouseStyle !== undefined ||
+        defaults.weekdayLabels !== undefined;
+    if (mode !== 'mcp' && usedMcpOnlyFlag) {
+        throw new Error('MCP startup defaults require MCP mode. Use e2a --mcp, or launch via the e2a-mcp compatibility alias.');
+    }
+    if (defaults.preferredTimezone && !isValidTimezone(defaults.preferredTimezone)) {
+        throw new Error(`Invalid timezone: ${defaults.preferredTimezone}`);
+    }
+    if (defaults.preferredHouseStyle && !VALID_HOUSE_STYLES.has(defaults.preferredHouseStyle)) {
+        throw new Error(`Invalid preferred house style: ${defaults.preferredHouseStyle} (must be one of P, W, K, E)`);
+    }
+    const mcpHelpRequested = mode === 'mcp' &&
+        cliArgv.length > 0 &&
+        cliArgv.every((arg) => arg === '--help' || arg === '-h');
+    if (mode === 'mcp' && cliArgv.length > 0 && !mcpHelpRequested) {
+        throw new Error(`Unexpected CLI arguments in MCP mode: ${cliArgv.join(' ')}`);
+    }
+    return {
+        mode,
+        cliArgv,
+        mcpHelpRequested,
+        mcpStartupDefaults: Object.freeze({ ...defaults }),
+    };
+}

package/dist/ephemeris.d.ts

@@ -85,6 +85,21 @@ export declare class EphemerisCalculator {
      * For example, 350° and 10° have a distance of 20°, not 340°.
      */
     calculateAspectAngle(lon1: number, lon2: number): number;
+    /**
+     * Convert ecliptic coordinates to local horizontal coordinates
+     *
+     * @param jd - Julian Day in UT
+     * @param position - Planetary ecliptic coordinates
+     * @param longitude - Observer longitude in degrees
+     * @param latitude - Observer latitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Horizontal coordinates including true and apparent altitude
+     */
+    getHorizontalCoordinates(jd: number, position: Pick<PlanetPosition, 'longitude' | 'latitude' | 'distance'>, longitude: number, latitude: number, altitude?: number): {
+        azimuth: number;
+        trueAltitude: number;
+        apparentAltitude: number;
+    };
     /**
      * Find all exact times when planet reaches a specific longitude
      *

package/dist/ephemeris.js

@@ -180,6 +180,39 @@ export class EphemerisCalculator {
         }
         return diff;
     }
+    /**
+     * Convert ecliptic coordinates to local horizontal coordinates
+     *
+     * @param jd - Julian Day in UT
+     * @param position - Planetary ecliptic coordinates
+     * @param longitude - Observer longitude in degrees
+     * @param latitude - Observer latitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Horizontal coordinates including true and apparent altitude
+     */
+    getHorizontalCoordinates(jd, position, longitude, latitude, altitude = 0) {
+        if (!this.eph)
+            throw new Error('Ephemeris not initialized');
+        if (!Number.isFinite(jd)) {
+            throw new Error(`Invalid Julian Day: ${jd} (must be finite)`);
+        }
+        if (!Number.isFinite(longitude) || !Number.isFinite(latitude) || !Number.isFinite(altitude)) {
+            throw new Error('Invalid geographic coordinates: longitude, latitude, and altitude must be finite');
+        }
+        const result = this.eph.azalt(jd, Constants.SE_ECL2HOR, [longitude, latitude, altitude], 0, 0, [
+            position.longitude,
+            position.latitude,
+            position.distance,
+        ]);
+        if (!Array.isArray(result) || result.length < 3) {
+            throw new Error('Failed to calculate horizontal coordinates');
+        }
+        return {
+            azimuth: result[0],
+            trueAltitude: result[1],
+            apparentAltitude: result[2],
+        };
+    }
     /**
      * Find all exact times when planet reaches a specific longitude
      *

package/dist/formatter.d.ts

@@ -1,2 +1,6 @@
-export declare function formatInTimezone(date: Date, timezone: string): string;
+interface FormatInTimezoneOptions {
+    weekday?: boolean;
+}
+export declare function formatInTimezone(date: Date, timezone: string, formatOptions?: FormatInTimezoneOptions): string;
 export declare function formatDateOnly(date: Date, timezone: string): string;
+export {};

package/dist/formatter.js

@@ -1,4 +1,4 @@
-export function formatInTimezone(date, timezone) {
+export function formatInTimezone(date, timezone, formatOptions = {}) {
     const options = {
         timeZone: timezone,
         year: 'numeric',
@@ -9,6 +9,9 @@ export function formatInTimezone(date, timezone) {
         hour12: true,
         timeZoneName: 'short',
     };
+    if (formatOptions.weekday) {
+        options.weekday = 'short';
+    }
     return new Intl.DateTimeFormat('en-US', options).format(date);
 }
 export function formatDateOnly(date, timezone) {

package/dist/index.d.ts

@@ -11,4 +11,5 @@
  * Uses Swiss Ephemeris for accurate astronomical calculations.
  * All calculations are tropical (not sidereal) and geocentric.
  */
-export declare function main(): Promise<void>;
+import type { McpStartupDefaults } from './entrypoint.js';
+export declare function main(startupDefaults?: Readonly<McpStartupDefaults>): Promise<void>;

package/dist/index.js

@@ -17,123 +17,72 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { AstroService } from './astro-service.js';
 import { logger } from './logger.js';
 import { getToolSpec, MCP_TOOL_SPECS } from './tool-registry.js';
-import { mcpError, mcpResult, missingNatalChart } from './tool-result.js';
-const server = new Server({
-    name: 'e2a-mcp',
-    version: '1.0.0',
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-/**
- * In-memory natal chart — the server's sole piece of mutable state.
- *
- * Lifecycle:
- *  - Starts as `null` when the process launches.
- *  - Set by `set_natal_chart`; overwritten on each call.
- *  - Persists for the lifetime of this stdio process (one per MCP client).
- *  - Tools that require it (`get_transits`, `get_houses`, `get_rise_set_times`,
- *    `generate_natal_chart`, `generate_transit_chart`) return a structured
- *    MISSING_NATAL_CHART error if it is null.
- *  - Use `get_server_status` to inspect whether a chart is loaded.
- *
- * Thread safety: Each MCP client connection spawns a separate Node.js process
- * via stdio transport, so this variable is isolated per client.
- * No synchronization needed as requests are serialized within a single process.
- */
-let natalChart = null;
-// Calculator instances (initialized on demand)
-const astroService = new AstroService();
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: MCP_TOOL_SPECS.map((spec) => ({
-            name: spec.name,
-            description: spec.description,
-            inputSchema: spec.inputSchema,
-        })),
-    };
-});
-/**
- * Handle MCP tool requests
- *
- * @param request - The MCP tool request
- * @returns Tool response with data or error
- * @throws Error for unhandled tools
- *
- * @remarks
- * Routes requests to appropriate handlers. Initializes ephemeris on first use.
- * All handlers return structured responses suitable for MCP clients.
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args = {} } = request.params;
-    try {
-        const spec = getToolSpec(name);
-        if (!spec) {
-            return mcpError({
-                code: 'INVALID_INPUT',
-                message: `Unknown tool: ${name}`,
-                retryable: false,
-                suggestedFix: 'Check the tool name against the list returned by ListTools.',
-            });
-        }
-        if (spec.requiresNatalChart && !natalChart) {
-            return mcpError(missingNatalChart());
-        }
-        const result = await spec.execute({
-            service: astroService,
-            natalChart,
-        }, args);
-        if (result.kind === 'state') {
-            if (result.natalChart !== undefined) {
-                natalChart = result.natalChart;
+import { mapToolErrorMessageToCode, mcpError, mcpResult, missingNatalChart, } from './tool-result.js';
+function createServer(startupDefaults = {}) {
+    const server = new Server({
+        name: 'e2a-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    let natalChart = null;
+    const astroService = new AstroService({ mcpStartupDefaults: startupDefaults });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: MCP_TOOL_SPECS.map((spec) => ({
+                name: spec.name,
+                description: spec.description,
+                inputSchema: spec.inputSchema,
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        try {
+            const spec = getToolSpec(name);
+            if (!spec) {
+                return mcpError({
+                    code: 'INVALID_INPUT',
+                    message: `Unknown tool: ${name}`,
+                    retryable: false,
+                    suggestedFix: 'Check the tool name against the list returned by ListTools.',
+                });
             }
-            return mcpResult(result.data, result.text);
-        }
-        return { content: result.content };
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        // Map known error patterns to appropriate codes
-        let code;
-        if (errorMessage.includes('Invalid date format') ||
-            errorMessage.includes('Invalid calendar date') ||
-            errorMessage.includes('Invalid month') ||
-            errorMessage.includes('Invalid day') ||
-            errorMessage.includes('days_ahead') ||
-            errorMessage.includes('max_orb') ||
-            errorMessage.includes('missing julianDay')) {
-            code = 'INVALID_INPUT';
-        }
-        else if (errorMessage.includes('Invalid timezone') || errorMessage.includes('timezone')) {
-            code = 'INVALID_TIMEZONE';
-        }
-        else if (errorMessage.includes('Invalid house system')) {
-            code = 'INVALID_HOUSE_SYSTEM';
-        }
-        else if (errorMessage.includes('Ephemeris') || errorMessage.includes('ephemeris')) {
-            code = 'EPHEMERIS_COMPUTE_FAILED';
-        }
-        else if (errorMessage.includes('write') ||
-            errorMessage.includes('ENOENT') ||
-            errorMessage.includes('EACCES')) {
-            code = 'FILE_WRITE_FAILED';
-        }
-        else if (errorMessage.includes('render') || errorMessage.includes('chart')) {
-            code = 'CHART_RENDER_FAILED';
+            if (spec.requiresNatalChart && !natalChart) {
+                return mcpError(missingNatalChart());
+            }
+            const result = await spec.execute({
+                service: astroService,
+                natalChart,
+            }, args);
+            if (result.kind === 'state') {
+                if (result.natalChart !== undefined) {
+                    natalChart = result.natalChart;
+                }
+                return mcpResult(result.data, result.text);
+            }
+            return { content: result.content };
         }
-        else {
-            code = 'INTERNAL_ERROR';
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const code = mapToolErrorMessageToCode(errorMessage);
+            return mcpError({
+                code,
+                message: errorMessage,
+                retryable: code === 'EPHEMERIS_COMPUTE_FAILED' || code === 'FILE_WRITE_FAILED',
+                details: { tool: name },
+            });
         }
-        return mcpError({
-            code,
-            message: errorMessage,
-            retryable: code === 'EPHEMERIS_COMPUTE_FAILED' || code === 'FILE_WRITE_FAILED',
-            details: { tool: name },
-        });
-    }
-});
-export async function main() {
+    });
+    return {
+        server,
+        astroService,
+    };
+}
+export async function main(startupDefaults = {}) {
+    const { server, astroService } = createServer(startupDefaults);
     logger.info('Initializing Swiss Ephemeris');
     await astroService.init();
     logger.info('Ephemeris initialized');

package/dist/loader.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+export declare function runEntrypoint(argv?: string[], invokedPath?: string): Promise<void>;

package/dist/loader.js

@@ -3,29 +3,67 @@ import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 // Set up browser globals for astrochart library BEFORE any imports
 import { JSDOM } from 'jsdom';
-const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
-globalThis.window = dom.window;
-globalThis.document = dom.window.document;
-globalThis.self = globalThis; // Critical: astrochart checks for 'self' - see https://github.com/AstroDraw/AstroChart/issues/85
-globalThis.SVGElement = dom.window.SVGElement;
-// Polyfill fetch for file:// URLs used by chart tooling in Node.
-const originalFetch = globalThis.fetch;
-globalThis.fetch = async (url, ...args) => {
-    const urlStr = url.toString();
-    if (urlStr.startsWith('file://')) {
-        const filePath = fileURLToPath(urlStr);
-        const buffer = await readFile(filePath);
-        return {
-            ok: true,
-            arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
-        };
+import { resolveEntrypoint } from './entrypoint.js';
+function initializeRuntime() {
+    const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+    globalThis.window = dom.window;
+    globalThis.document = dom.window.document;
+    globalThis.self = globalThis; // Critical: astrochart checks for 'self' - see https://github.com/AstroDraw/AstroChart/issues/85
+    globalThis.SVGElement = dom.window.SVGElement;
+    // Polyfill fetch for file:// URLs used by chart tooling in Node.
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (url, ...args) => {
+        const urlStr = url.toString();
+        if (urlStr.startsWith('file://')) {
+            const filePath = fileURLToPath(urlStr);
+            const buffer = await readFile(filePath);
+            return {
+                ok: true,
+                arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+            };
+        }
+        return originalFetch(url, ...args);
+    };
+}
+function emitMcpHelp(invokedPath = process.argv[1] ?? '') {
+    const invokedName = invokedPath.includes('e2a-mcp') ? 'e2a-mcp' : 'e2a';
+    const launchExample = invokedName === 'e2a-mcp'
+        ? 'e2a-mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels'
+        : 'e2a --mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels';
+    console.log(`Usage: ${invokedName === 'e2a-mcp' ? 'e2a-mcp' : 'e2a --mcp'} [options]
+
+Start the ether-to-astro MCP server with optional deterministic startup defaults.
+
+Options:
+  --preferred-tz <iana>           Default reporting timezone for MCP surfaces
+  --preferred-house-style <P|W|K|E>
+                                  Default house-style preference for MCP surfaces
+  --weekday-labels                Include weekday labels in human-readable MCP text output
+  --no-weekday-labels             Disable weekday labels in human-readable MCP text output
+  -h, --help                      Show this help
+
+Example:
+  ${launchExample}`);
+}
+export async function runEntrypoint(argv = process.argv.slice(2), invokedPath = process.argv[1]) {
+    initializeRuntime();
+    const resolved = resolveEntrypoint(argv, invokedPath);
+    if (resolved.mode === 'mcp') {
+        if (resolved.mcpHelpRequested) {
+            emitMcpHelp(invokedPath);
+            return;
+        }
+        const { main } = await import('./index.js');
+        await main(resolved.mcpStartupDefaults);
+        return;
     }
-    return originalFetch(url, ...args);
-};
-// Use dynamic import() so the above globals are set BEFORE index.js (and charts.js) load
-import('./index.js').then(({ main }) => {
-    main().catch((error) => {
-        console.error('[ERROR] Failed to start server:', error);
+    const { runCli } = await import('./cli.js');
+    const code = await runCli(resolved.cliArgv);
+    process.exit(code);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runEntrypoint().catch((error) => {
+        console.error('[ERROR] Failed to start program:', error);
         process.exit(1);
     });
-});
+}

package/dist/mcp-alias.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp-alias.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runEntrypoint } from './loader.js';
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runEntrypoint(['--mcp', ...process.argv.slice(2)], process.argv[1]).catch((error) => {
+        console.error('[ERROR] Failed to start program:', error);
+        process.exit(1);
+    });
+}

package/dist/time-utils.d.ts

@@ -66,3 +66,11 @@ export declare function getTimezoneOffset(date: Date, timezone: string): number;
  * @returns UTC Date representing the new local date/time
  */
 export declare function addLocalDays(local: LocalDateTime, timezone: string, days: number): Date;
+/**
+ * Format a UTC instant as a local ISO-8601 timestamp with timezone offset.
+ *
+ * @param utc - UTC Date object
+ * @param timezone - IANA timezone string
+ * @returns Local timestamp in the form YYYY-MM-DDTHH:mm:ss±HH:MM
+ */
+export declare function formatLocalTimestampWithOffset(utc: Date, timezone: string): string;

package/dist/time-utils.js

@@ -134,3 +134,19 @@ export function addLocalDays(local, timezone, days) {
     const zonedDateTime = newPlainDateTime.toZonedDateTime(timezone);
     return new Date(zonedDateTime.epochMilliseconds);
 }
+/**
+ * Format a UTC instant as a local ISO-8601 timestamp with timezone offset.
+ *
+ * @param utc - UTC Date object
+ * @param timezone - IANA timezone string
+ * @returns Local timestamp in the form YYYY-MM-DDTHH:mm:ss±HH:MM
+ */
+export function formatLocalTimestampWithOffset(utc, timezone) {
+    const local = utcToLocal(utc, timezone);
+    const offsetMinutes = getTimezoneOffset(utc, timezone);
+    const offsetSign = offsetMinutes >= 0 ? '+' : '-';
+    const offsetAbs = Math.abs(offsetMinutes);
+    const offsetHours = String(Math.floor(offsetAbs / 60)).padStart(2, '0');
+    const offsetMins = String(offsetAbs % 60).padStart(2, '0');
+    return `${String(local.year).padStart(4, '0')}-${String(local.month).padStart(2, '0')}-${String(local.day).padStart(2, '0')}T${String(local.hour).padStart(2, '0')}:${String(local.minute).padStart(2, '0')}:${String(local.second ?? 0).padStart(2, '0')}${offsetSign}${offsetHours}:${offsetMins}`;
+}