fix: address review-4180927536 — stderr logs, range filenames, --tom alias, CliArgsError

Agent-Logs-Url: https://github.com/Hack23/riksdagsmonitor/sessions/ed2d6569-2714-4ed0-9fc9-55bf7937ee66

Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>

Author: Copilot

scripts/fetch-calendar.ts

@@ -665,10 +665,10 @@ export async function fetchCalendarWithFallback(
     }
 
     try {
-      console.log(`  🔄 [fetch-calendar] MCP primary attempt ${attempt + 1}/${maxRetries + 1}…`);
+      console.error(`  🔄 [fetch-calendar] MCP primary attempt ${attempt + 1}/${maxRetries + 1}…`);
       const raw = await callMcpCalendarEvents(from, to, resolved);
       const events = raw.map(normalizeMcpCalendarEvent);
-      console.log(`  ✅ [fetch-calendar] MCP primary succeeded — ${events.length} events`);
+      console.error(`  ✅ [fetch-calendar] MCP primary succeeded — ${events.length} events`);
 
       return {
         events,
@@ -691,11 +691,11 @@ export async function fetchCalendarWithFallback(
   }
 
   // ── Web fallback path ──────────────────────────────────────────────────
-  console.log(`  🔄 [fetch-calendar] Falling back to riksdagen.se/sv/kalendarium/…`);
+  console.error(`  🔄 [fetch-calendar] Falling back to riksdagen.se/sv/kalendarium/…`);
   let fallbackError: string | undefined;
   try {
     const events = await fetchWebCalendar(from, to, resolved);
-    console.log(`  ✅ [fetch-calendar] Web fallback succeeded — ${events.length} events`);
+    console.error(`  ✅ [fetch-calendar] Web fallback succeeded — ${events.length} events`);
 
     return {
       events,
@@ -737,25 +737,29 @@ const REPO_ROOT = path.resolve(__dirname, '..');
 const CALENDAR_DIR = path.join(REPO_ROOT, 'data', 'calendar');
 
 /**
- * Write a `CalendarFetchResult` to `data/calendar/{from}.json`.
+ * Write a `CalendarFetchResult` to `data/calendar/{from}_{to}.json`.
  *
  * The file is an object with `{ manifest, events }` so that consumers can
  * load a single file and get both the data and the provenance record.
+ * Including `to` in the filename prevents collisions when the same `from`
+ * date is fetched with different ranges (e.g. week-ahead vs month-ahead).
  */
 export function persistCalendarJson(
   from: string,
   result: CalendarFetchResult,
   outputDir: string = CALENDAR_DIR,
 ): string {
   fs.mkdirSync(outputDir, { recursive: true });
-  const outputPath = path.join(outputDir, `${from}.json`);
+  const dateTo = result.manifest.dateTo ?? from;
+  const fileName = dateTo && dateTo !== from ? `${from}_${dateTo}.json` : `${from}.json`;
+  const outputPath = path.join(outputDir, fileName);
   const payload = {
     schema: 'riksdagsmonitor-calendar/1.0',
     manifest: result.manifest,
     events: result.events,
   };
   fs.writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf8');
-  console.log(`  💾 [fetch-calendar] Persisted ${result.events.length} events → ${outputPath}`);
+  console.error(`  💾 [fetch-calendar] Persisted ${result.events.length} events → ${outputPath}`);
   return outputPath;
 }
 
@@ -791,7 +795,20 @@ export function formatManifestMarkdown(manifest: CalendarFetchManifest): string
   return lines.join('\n');
 }
 
-/** Parse CLI argv into `{ from, to, persist }`. */
+/** Thrown by `parseCalendarArgs` for invalid CLI arguments (exit code 2). */
+export class CliArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CliArgsError';
+  }
+}
+
+/**
+ * Parse CLI argv into `{ from, to, persist }`.
+ *
+ * Accepts `--to` (preferred) and `--tom` (Swedish alias, used in repo docs)
+ * as the end-date flag. Throws `CliArgsError` for invalid arguments.
+ */
 export function parseCalendarArgs(argv: readonly string[]): {
   from: string;
   to: string;
@@ -813,29 +830,31 @@ export function parseCalendarArgs(argv: readonly string[]): {
   }
   const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
   const from = flags.get('from') ?? '';
-  const to = flags.get('to') ?? '';
+  // Accept both `--to` and `--tom` (Swedish alias used in repo docs).
+  const to = flags.get('to') ?? flags.get('tom') ?? '';
   if (!ISO_DATE_RE.test(from)) {
-    throw new Error(`--from must be an ISO 8601 date (YYYY-MM-DD), got: "${from}"`);
+    throw new CliArgsError(`--from must be an ISO 8601 date (YYYY-MM-DD), got: "${from}"`);
   }
   if (!ISO_DATE_RE.test(to)) {
-    throw new Error(`--to must be an ISO 8601 date (YYYY-MM-DD), got: "${to}"`);
+    throw new CliArgsError(`--to must be an ISO 8601 date (YYYY-MM-DD), got: "${to}"`);
   }
   return { from, to, persist: booleans.has('persist') };
 }
 
 async function main(): Promise<void> {
   const args = parseCalendarArgs(process.argv.slice(2));
-  console.log(`📅 [fetch-calendar] Fetching ${args.from} → ${args.to}`);
+  console.error(`📅 [fetch-calendar] Fetching ${args.from} → ${args.to}`);
 
   const result = await fetchCalendarWithFallback(args.from, args.to);
 
-  console.log(formatManifestMarkdown(result.manifest));
+  // Manifest is human-readable status info → stderr, not stdout.
+  console.error(formatManifestMarkdown(result.manifest));
 
   if (args.persist) {
     persistCalendarJson(args.from, result);
   } else {
     // Print JSON to stdout for piping / agentic workflow consumption.
-    console.log(JSON.stringify(result, null, 2));
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   }
 
   if (result.manifest.path === 'none') {
@@ -847,6 +866,7 @@ async function main(): Promise<void> {
 if (path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '')) {
   main().catch((err: unknown) => {
     console.error('❌ [fetch-calendar] Fatal error:', err instanceof Error ? err.message : err);
-    process.exit(1);
+    // Bad CLI arguments → exit code 2 (per module header & repo convention).
+    process.exit(err instanceof CliArgsError ? 2 : 1);
   });
 }

tests/fetch-calendar.test.ts

@@ -35,6 +35,7 @@ import {
   formatManifestMarkdown,
   parseCalendarArgs,
   persistCalendarJson,
+  CliArgsError,
   type CalendarFetchConfig,
   type CalendarEvent,
 } from '../scripts/fetch-calendar.js';
@@ -722,6 +723,28 @@ describe('parseCalendarArgs', () => {
       parseCalendarArgs(['--from', '28-04-2026', '--to', '2026-05-04']),
     ).toThrow(/ISO 8601/);
   });
+
+  it('accepts --tom as an alias for --to (Swedish, used in repo docs)', () => {
+    const args = parseCalendarArgs(['--from', '2026-04-28', '--tom', '2026-05-04']);
+    expect(args.from).toBe('2026-04-28');
+    expect(args.to).toBe('2026-05-04');
+  });
+
+  it('prefers --to over --tom when both are provided', () => {
+    const args = parseCalendarArgs([
+      '--from', '2026-04-28',
+      '--to', '2026-05-04',
+      '--tom', '2026-05-31',
+    ]);
+    expect(args.to).toBe('2026-05-04');
+  });
+
+  it('throws CliArgsError (typed) for invalid arguments', () => {
+    expect(() => parseCalendarArgs(['--to', '2026-05-04'])).toThrow(CliArgsError);
+    expect(() =>
+      parseCalendarArgs(['--from', 'bogus', '--to', '2026-05-04']),
+    ).toThrow(CliArgsError);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -945,4 +968,22 @@ describe('persistCalendarJson', () => {
     const outPath = persistCalendarJson('2026-05-01', result, outputDir);
     expect(outPath).toBe(path.join(outputDir, '2026-05-01.json'));
   });
+
+  it('uses {from}_{dateTo}.json when range spans multiple days', () => {
+    const outputDir = path.join(tmpDir, 'calendar');
+    const result = {
+      manifest: {
+        path: 'mcp-primary' as const,
+        date: '2026-04-28',
+        dateTo: '2026-05-04',
+        eventCount: 0,
+        fetchedAt: '2026-04-28T00:00:00.000Z',
+      },
+      events: [],
+    };
+
+    const outPath = persistCalendarJson('2026-04-28', result, outputDir);
+    expect(outPath).toBe(path.join(outputDir, '2026-04-28_2026-05-04.json'));
+    expect(fs.existsSync(outPath)).toBe(true);
+  });
 });