ether-to-astro 1.0.0

package/tests/unit/astro-service.test.ts

@@ -0,0 +1,323 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AstroService, parseDateOnlyInput } from '../../src/astro-service.js';
+import type { NatalChart, PlanetPosition, RiseSetTime } from '../../src/types.js';
+
+function makePlanet(planet: PlanetPosition['planet'], longitude: number): PlanetPosition {
+  return {
+    planetId: 0,
+    planet,
+    longitude,
+    latitude: 0,
+    distance: 1,
+    speed: 1,
+    sign: 'Aries',
+    degree: longitude % 30,
+    isRetrograde: false,
+  };
+}
+
+function makeNatalChart(): NatalChart {
+  return {
+    name: 'Test User',
+    birthDate: { year: 1990, month: 6, day: 12, hour: 14, minute: 35 },
+    location: { latitude: 37.7749, longitude: -122.4194, timezone: 'America/Los_Angeles' },
+    planets: [makePlanet('Sun', 10), makePlanet('Moon', 20)],
+    julianDay: 2451545,
+    houseSystem: 'P',
+    utcDateTime: { year: 1990, month: 6, day: 12, hour: 21, minute: 35 },
+  };
+}
+
+function makeService() {
+  const ephem = {
+    eph: {},
+    init: vi.fn(async () => {}),
+    dateToJulianDay: vi.fn(() => 2451545),
+    getAllPlanets: vi.fn(() => [makePlanet('Sun', 204), makePlanet('Moon', 270)]),
+  };
+  const houseCalc = {
+    calculateHouses: vi.fn(() => ({
+      ascendant: 270,
+      mc: 204,
+      cusps: [0, 270, 300, 330, 0, 30, 60, 90, 120, 150, 204, 240, 260],
+      system: 'W' as const,
+    })),
+  };
+  const transitCalc = {
+    findTransits: vi.fn(() => [
+      {
+        transitingPlanet: 'Mars',
+        natalPlanet: 'Sun',
+        aspect: 'square',
+        orb: 1.25,
+        isApplying: true,
+        exactTimeStatus: 'within_preview' as const,
+        transitLongitude: 100,
+        natalLongitude: 10,
+        exactTime: new Date('2024-03-27T12:00:00Z'),
+      },
+    ]),
+  };
+  const riseSetCalc = {
+    getAllRiseSet: vi.fn(async () => [
+      {
+        planet: 'Sun',
+        rise: new Date('2024-03-26T13:00:00Z'),
+        set: new Date('2024-03-27T01:00:00Z'),
+      },
+    ] as RiseSetTime[]),
+  };
+  const eclipseCalc = {
+    findNextSolarEclipse: vi.fn(() => ({
+      type: 'solar' as const,
+      date: new Date('2024-04-08T18:00:00Z'),
+      eclipseType: 'Total',
+      maxTime: new Date('2024-04-08T18:00:00Z'),
+    })),
+    findNextLunarEclipse: vi.fn(() => null),
+  };
+  const chartRenderer = {
+    generateNatalChart: vi.fn(async (_chart, _theme, format) => {
+      if (format === 'svg') return '<svg>ok</svg>';
+      return Buffer.from([1, 2, 3]);
+    }),
+    generateTransitChart: vi.fn(async (_chart, _date, _theme, format) => {
+      if (format === 'svg') return '<svg>transit</svg>';
+      return Buffer.from([4, 5, 6]);
+    }),
+  };
+  const writeFile = vi.fn(async () => {});
+  const now = vi.fn(() => new Date('2024-03-26T12:00:00Z'));
+
+  const service = new AstroService({
+    ephem: ephem as any,
+    houseCalc: houseCalc as any,
+    transitCalc: transitCalc as any,
+    riseSetCalc: riseSetCalc as any,
+    eclipseCalc: eclipseCalc as any,
+    chartRenderer: chartRenderer as any,
+    writeFile,
+    now,
+  });
+
+  return { service, ephem, houseCalc, transitCalc, riseSetCalc, eclipseCalc, chartRenderer, writeFile, now };
+}
+
+describe('When using AstroService', () => {
+  it('Given a date-only input, then it parses valid values and rejects invalid calendar parts', () => {
+    expect(parseDateOnlyInput('2024-03-26')).toEqual({
+      year: 2024,
+      month: 3,
+      day: 26,
+      hour: 12,
+      minute: 0,
+    });
+    expect(() => parseDateOnlyInput('2024-13-01')).toThrow(/Invalid month/);
+    expect(() => parseDateOnlyInput('2024-02-00')).toThrow(/Invalid day/);
+  });
+
+  it('Given injected dependencies, then init initializes ephemeris', async () => {
+    const { service, ephem } = makeService();
+    await service.init();
+    expect(ephem.init).toHaveBeenCalledTimes(1);
+    expect(service.isInitialized()).toBe(true);
+  });
+
+  it('Given a polar latitude chart, then setNatalChart returns fallback house system details', () => {
+    const { service, houseCalc } = makeService();
+    const result = service.setNatalChart({
+      name: 'Polar User',
+      year: 1990,
+      month: 6,
+      day: 12,
+      hour: 14,
+      minute: 35,
+      latitude: 78,
+      longitude: 15,
+      timezone: 'UTC',
+      house_system: 'P',
+    });
+
+    expect(houseCalc.calculateHouses).toHaveBeenCalled();
+    expect(result.chart.houseSystem).toBe('W');
+    expect(result.data).toMatchObject({
+      name: 'Polar User',
+      requestedHouseSystem: 'P',
+      resolvedHouseSystem: 'W',
+      isPolar: true,
+    });
+  });
+
+  it('Given missing Sun or Moon data, then setNatalChart throws a clear error', () => {
+    const { service, ephem } = makeService();
+    ephem.getAllPlanets.mockReturnValue([makePlanet('Sun', 200)]);
+    expect(() =>
+      service.setNatalChart({
+        name: 'No Moon',
+        year: 1990,
+        month: 1,
+        day: 1,
+        hour: 1,
+        minute: 1,
+        latitude: 1,
+        longitude: 1,
+        timezone: 'UTC',
+      })
+    ).toThrow(/Sun\/Moon/);
+  });
+
+  it('Given transit filters, then getTransits returns filtered data and optional mundane payload', () => {
+    const { service } = makeService();
+    const natal = makeNatalChart();
+    const result = service.getTransits(natal, {
+      include_mundane: true,
+      days_ahead: 1,
+      max_orb: 2,
+      exact_only: true,
+      applying_only: true,
+    });
+
+    expect(result.data).toHaveProperty('transits');
+    expect(result.data).toHaveProperty('mundane');
+    expect(result.text).toContain('Transits');
+  });
+
+  it('Given exact-time lookup metadata, then getTransits serializes exactTimeStatus', () => {
+    const { service, transitCalc } = makeService();
+    transitCalc.findTransits.mockReturnValue([
+      {
+        transitingPlanet: 'Mars',
+        natalPlanet: 'Sun',
+        aspect: 'square',
+        orb: 1.25,
+        isApplying: true,
+        exactTimeStatus: 'outside_preview',
+        transitLongitude: 100,
+        natalLongitude: 10,
+        exactTime: undefined,
+      },
+    ]);
+
+    const result = service.getTransits(makeNatalChart());
+    expect((result.data as any).transits[0]).toMatchObject({
+      exactTimeStatus: 'outside_preview',
+      exactTime: undefined,
+    });
+  });
+
+  it('Given a natal chart location, then getRiseSetTimes returns ISO payload and readable text', async () => {
+    const { service, riseSetCalc } = makeService();
+    const result = await service.getRiseSetTimes(makeNatalChart());
+    expect(riseSetCalc.getAllRiseSet).toHaveBeenCalledTimes(1);
+    expect(result.data).toMatchObject({
+      timezone: 'America/Los_Angeles',
+    });
+    expect(result.text).toContain('Rise/Set Times');
+  });
+
+  it('Given eclipse availability, then getNextEclipses returns summary or empty-state text', () => {
+    const { service, eclipseCalc } = makeService();
+    const withOne = service.getNextEclipses('UTC');
+    expect(withOne.data).toMatchObject({ timezone: 'UTC' });
+    expect(withOne.text).toContain('Upcoming Eclipses');
+
+    eclipseCalc.findNextSolarEclipse.mockReturnValue(null);
+    const none = service.getNextEclipses('UTC');
+    expect(none.text).toContain('No eclipses found');
+  });
+
+  it('Given current planetary motion, then getRetrogradePlanets returns retrograde payload', () => {
+    const { service, ephem } = makeService();
+    ephem.getAllPlanets.mockReturnValue([
+      { ...makePlanet('Mercury', 10), isRetrograde: true, speed: -0.2 },
+      { ...makePlanet('Venus', 20), isRetrograde: false, speed: 1.2 },
+    ]);
+
+    const result = service.getRetrogradePlanets('UTC');
+    expect(result.data).toMatchObject({ timezone: 'UTC' });
+    expect(result.text).toContain('Mercury');
+  });
+
+  it('Given output_path for natal chart generation, then it writes the file and returns path text', async () => {
+    const { service, writeFile } = makeService();
+    const result = await service.generateNatalChart(makeNatalChart(), {
+      format: 'svg',
+      output_path: '/tmp/chart.svg',
+      theme: 'light',
+    });
+    expect(writeFile).toHaveBeenCalledWith('/tmp/chart.svg', '<svg>ok</svg>', 'utf-8');
+    expect(result.outputPath).toBe('/tmp/chart.svg');
+  });
+
+  it('Given binary chart output, then it returns base64 image payload with mime type', async () => {
+    const { service } = makeService();
+    const result = await service.generateTransitChart(makeNatalChart(), {
+      format: 'png',
+      theme: 'dark',
+    });
+    expect(result.image?.mimeType).toBe('image/png');
+    expect(result.image?.data).toBe(Buffer.from([4, 5, 6]).toString('base64'));
+  });
+
+  it('Given natal chart presence or absence, then getServerStatus reports correct state', () => {
+    const { service } = makeService();
+    const empty = service.getServerStatus(null);
+    const loaded = service.getServerStatus(makeNatalChart());
+    expect(empty.data).toMatchObject({ hasNatalChart: false });
+    expect(loaded.data).toMatchObject({ hasNatalChart: true });
+  });
+
+  it('Given invalid transit filters or missing Julian day, then validation errors are thrown', () => {
+    const { service } = makeService();
+    expect(() => service.getTransits(makeNatalChart(), { days_ahead: -1 })).toThrow(/days_ahead/);
+    expect(() => service.getTransits(makeNatalChart(), { max_orb: -1 })).toThrow(/max_orb/);
+    expect(() => service.getHouses({ ...makeNatalChart(), julianDay: undefined })).toThrow(/missing julianDay/i);
+  });
+
+  it('Given empty transit/retrograde results, then user-facing empty-state text is returned', () => {
+    const { service, transitCalc, ephem } = makeService();
+    transitCalc.findTransits.mockReturnValue([]);
+    ephem.getAllPlanets.mockReturnValue([{ ...makePlanet('Sun', 10), isRetrograde: false, speed: 1 }]);
+    const transits = service.getTransits(makeNatalChart(), { include_mundane: false });
+    expect(transits.text).toContain('No transits found');
+    const retro = service.getRetrogradePlanets('UTC');
+    expect(retro.text).toContain('No planets are currently retrograde');
+  });
+
+  it('Given chart format/output variants, then chart generation returns the correct branch payload', async () => {
+    const { service, chartRenderer, writeFile } = makeService();
+    chartRenderer.generateNatalChart.mockResolvedValueOnce('<svg>inline</svg>');
+    const inlineSvg = await service.generateNatalChart(makeNatalChart(), { format: 'svg' });
+    expect(inlineSvg.svg).toBe('<svg>inline</svg>');
+
+    chartRenderer.generateNatalChart.mockResolvedValueOnce(Buffer.from([9, 9]));
+    const inlinePng = await service.generateNatalChart(makeNatalChart(), { format: 'png' });
+    expect(inlinePng.image?.mimeType).toBe('image/png');
+
+    chartRenderer.generateTransitChart.mockResolvedValueOnce('<svg>transit-inline</svg>');
+    const transitSvg = await service.generateTransitChart(makeNatalChart(), { format: 'svg', date: '2024-03-26' });
+    expect(transitSvg.svg).toContain('transit-inline');
+
+    chartRenderer.generateTransitChart.mockResolvedValueOnce(Buffer.from([8, 8]));
+    const saved = await service.generateTransitChart(makeNatalChart(), {
+      format: 'webp',
+      output_path: '/tmp/transit.webp',
+      date: '2024-03-26',
+    });
+    expect(writeFile).toHaveBeenCalledWith('/tmp/transit.webp', Buffer.from([8, 8]));
+    expect(saved.outputPath).toBe('/tmp/transit.webp');
+  });
+
+  it('Given both solar and lunar eclipses exist, then both are included in the response', () => {
+    const { service, eclipseCalc } = makeService();
+    eclipseCalc.findNextLunarEclipse.mockReturnValue({
+      type: 'lunar',
+      date: new Date('2024-09-18T00:00:00Z'),
+      eclipseType: 'Partial',
+      maxTime: new Date('2024-09-18T00:00:00Z'),
+    });
+    const result = service.getNextEclipses('UTC');
+    expect((result.data as any).eclipses).toHaveLength(2);
+    expect(result.text).toContain('Next Lunar Eclipse');
+  });
+});

package/tests/unit/chart-types.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { getThemeSettings } from '../../src/chart-types.js';
+
+describe('When selecting chart theme settings', () => {
+  it('Given dark theme and transparency options, then background colors are resolved correctly', () => {
+    const dark = getThemeSettings('dark', false);
+    const darkTransparent = getThemeSettings('dark', true);
+    expect(dark.COLOR_BACKGROUND).toBe('#282c34');
+    expect(darkTransparent.COLOR_BACKGROUND).toBe('transparent');
+  });
+
+  it('Given light theme and transparency options, then background colors are resolved correctly', () => {
+    const light = getThemeSettings('light', false);
+    const lightTransparent = getThemeSettings('light', true);
+    expect(light.COLOR_BACKGROUND).toBe('#ffffff');
+    expect(lightTransparent.COLOR_BACKGROUND).toBe('transparent');
+  });
+});

package/tests/unit/charts-errors.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { ChartRenderer } from '../../src/charts.js';
+
+describe('When chart rendering inputs are invalid', () => {
+  it('Given a natal chart missing Julian Day, then renderer throws a clear error', async () => {
+    const renderer = new ChartRenderer(
+      { getAllPlanets: () => [] } as any,
+      { calculateHouses: () => ({ cusps: Array(13).fill(0) }) } as any
+    );
+    await expect(
+      renderer.generateNatalChart({
+        name: 'Missing JD',
+        birthDate: { year: 2000, month: 1, day: 1, hour: 0, minute: 0 },
+        location: { latitude: 0, longitude: 0, timezone: 'UTC' },
+      } as any)
+    ).rejects.toThrow(/missing Julian Day/i);
+  });
+
+  it('Given a missing chart container in DOM, then SVG extraction throws', () => {
+    const renderer = new ChartRenderer({} as any, {} as any);
+    (renderer as any).dom = {
+      window: {
+        document: {
+          getElementById: () => null,
+        },
+      },
+    };
+    expect(() => (renderer as any).extractSVG()).toThrow(/container not found/i);
+  });
+
+  it('Given rendered output without an SVG element, then SVG extraction throws', () => {
+    const renderer = new ChartRenderer({} as any, {} as any);
+    (renderer as any).dom = {
+      window: {
+        document: {
+          getElementById: () => ({ querySelector: () => null }),
+        },
+      },
+    };
+    expect(() => (renderer as any).extractSVG()).toThrow(/no SVG element/i);
+  });
+});

package/tests/unit/charts.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ChartRenderer } from '../../src/charts.js';
+import { EphemerisCalculator } from '../../src/ephemeris.js';
+import { HouseCalculator } from '../../src/houses.js';
+import { bowenYangChart } from '../fixtures/bowen-yang-chart.js';
+
+describe('When an AI requests "Generate a chart for Bowen"', () => {
+  let ephem: EphemerisCalculator;
+  let houseCalc: HouseCalculator;
+  let chartRenderer: ChartRenderer;
+
+  beforeAll(async () => {
+    ephem = new EphemerisCalculator();
+    await ephem.init();
+    houseCalc = new HouseCalculator(ephem);
+    chartRenderer = new ChartRenderer(ephem, houseCalc);
+  });
+
+  describe('Given a request for SVG natal chart', () => {
+    it('should generate SVG natal chart', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      expect(typeof result).toBe('string');
+      expect(result).toContain('<svg');
+      expect(result).toContain('</svg>');
+    });
+
+    it('should include zodiac signs in SVG', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      expect(result).toContain('astrology-radix-signs');
+    });
+
+    it('should include planet symbols in SVG', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      expect(result).toContain('astrology');
+    });
+  });
+
+  describe('When generating PNG natal chart', () => {
+    it('should generate PNG buffer', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'png');
+      
+      expect(Buffer.isBuffer(result)).toBe(true);
+      expect((result as Buffer).length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('When generating WebP natal chart', () => {
+    it('should generate WebP buffer', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'webp');
+      
+      expect(Buffer.isBuffer(result)).toBe(true);
+      expect((result as Buffer).length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('When applying light theme', () => {
+    it('should use white background for light theme', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      expect(result).toContain('#ffffff');
+    });
+
+    it('should apply light theme zodiac colors', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      // Should contain custom light colors
+      expect(result).toContain('#ffffff'); // White
+      expect(result).toContain('#c1e6d1'); // Mint
+    });
+  });
+
+  describe('When applying dark theme', () => {
+    it('should use dark background for dark theme', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'dark', 'svg');
+      
+      expect(result).toContain('#282c34');
+    });
+
+    it('should apply dark theme zodiac colors', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'dark', 'svg');
+      
+      // Should contain custom dark colors
+      expect(result).toContain('#282c34'); // Dark gray
+      expect(result).toContain('#8545b0'); // Purple
+    });
+  });
+
+  describe('When rendering aspect lines', () => {
+    it('should include aspect lines in chart', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      expect(result).toContain('aspects');
+    });
+
+    it('should render squares, trines, oppositions, and sextiles', async () => {
+      const result = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'svg');
+      
+      // Aspect group should be present
+      expect(result).toContain('astrology-aspects');
+    });
+  });
+
+  describe('When generating transit chart overlay', () => {
+    it('should generate transit chart with current date', async () => {
+      const result = await chartRenderer.generateTransitChart(bowenYangChart, undefined, 'light', 'svg');
+      
+      expect(typeof result).toBe('string');
+      expect(result).toContain('<svg');
+    });
+
+    it('should generate transit chart for specific date', async () => {
+      const transitDate = new Date('2024-01-01');
+      const result = await chartRenderer.generateTransitChart(bowenYangChart, transitDate, 'light', 'svg');
+      
+      expect(typeof result).toBe('string');
+      expect(result).toContain('<svg');
+    });
+
+    it('should overlay transits on natal chart', async () => {
+      const result = await chartRenderer.generateTransitChart(bowenYangChart, undefined, 'light', 'svg');
+      
+      // Should contain both natal and transit data
+      expect(result).toContain('radix');
+    });
+  });
+
+  describe('When handling different image formats', () => {
+    it('should convert SVG to PNG with correct background', async () => {
+      const pngResult = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'png');
+      
+      expect(Buffer.isBuffer(pngResult)).toBe(true);
+    });
+
+    it('should convert SVG to WebP with correct background', async () => {
+      const webpResult = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'webp');
+      
+      expect(Buffer.isBuffer(webpResult)).toBe(true);
+    });
+
+    it('should use theme-appropriate background in PNG conversion', async () => {
+      const lightPng = await chartRenderer.generateNatalChart(bowenYangChart, 'light', 'png');
+      const darkPng = await chartRenderer.generateNatalChart(bowenYangChart, 'dark', 'png');
+      
+      expect(Buffer.isBuffer(lightPng)).toBe(true);
+      expect(Buffer.isBuffer(darkPng)).toBe(true);
+      
+      // Dark and light should produce different results
+      expect(Buffer.isBuffer(lightPng) && Buffer.isBuffer(darkPng)).toBe(true);
+      if (Buffer.isBuffer(lightPng) && Buffer.isBuffer(darkPng)) {
+        expect(lightPng.equals(darkPng)).toBe(false);
+      }
+    });
+  });
+});

package/tests/unit/cli-commands.test.ts

@@ -0,0 +1,82 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { runCli } from '../../src/cli.js';
+import { makeTempDir } from '../helpers/temp.js';
+
+const natalArgs = [
+  '--name', 'Tester',
+  '--year', '1990',
+  '--month', '6',
+  '--day', '12',
+  '--hour', '14',
+  '--minute', '35',
+  '--latitude', '37.7749',
+  '--longitude', '-122.4194',
+  '--timezone', 'UTC',
+];
+
+describe.sequential('When exercising CLI command handlers end-to-end', () => {
+  it('Given inline natal arguments, then key command handlers execute successfully', async () => {
+    const io = { stdout: vi.fn(), stderr: vi.fn() };
+
+    const commands: string[][] = [
+      ['set-natal-chart', ...natalArgs],
+      ['get-retrograde-planets'],
+      ['get-asteroid-positions'],
+      ['get-next-eclipses'],
+      ['get-transits', ...natalArgs, '--categories', 'all', '--days-ahead', '1', '--max-orb', '5'],
+      ['get-houses', ...natalArgs, '--system', 'W'],
+      ['get-rise-set-times', ...natalArgs],
+      ['generate-natal-chart', ...natalArgs, '--format', 'svg'],
+      ['generate-transit-chart', ...natalArgs, '--format', 'svg', '--date', '2024-03-26'],
+    ];
+
+    for (const cmd of commands) {
+      const code = await runCli(cmd, io);
+      expect(code).toBe(0);
+    }
+  });
+
+  it('Given a valid profile file, then profiles list/show/validate all execute successfully', async () => {
+    const dir = await makeTempDir('cli-profile-commands');
+    const file = path.join(dir, '.astro.json');
+    await writeFile(
+      file,
+      JSON.stringify({
+        version: 1,
+        defaultProfile: 'default',
+        profiles: {
+          default: {
+            name: 'Test',
+            year: 1990,
+            month: 1,
+            day: 1,
+            hour: 1,
+            minute: 1,
+            latitude: 1,
+            longitude: 1,
+            timezone: 'UTC',
+          },
+        },
+      }),
+      'utf8'
+    );
+
+    const io = { stdout: vi.fn(), stderr: vi.fn() };
+    expect(await runCli(['profiles', 'list', '--profile-file', file], io)).toBe(0);
+    expect(await runCli(['profiles', 'show', '--profile', 'default', '--profile-file', file], io)).toBe(0);
+    expect(await runCli(['profiles', 'validate', '--profile-file', file], io)).toBe(0);
+  });
+
+  it('Given malformed numeric arguments, then CLI returns a validation error payload', async () => {
+    const stderr: string[] = [];
+    const code = await runCli(
+      ['get-transits', ...natalArgs, '--days-ahead', 'nope'],
+      { stdout: vi.fn(), stderr: (m) => stderr.push(m) }
+    );
+    expect(code).toBe(1);
+    const payload = JSON.parse(stderr.join('\n')) as { code: string };
+    expect(payload.code).toBe('CLI_ERROR');
+  });
+});