@remnic/core 9.65.6 → 9.65.7

package/src/location/scheduler.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Location auto-sync scheduler regression (issue #2047): the maintenance
+ * scheduler arms this only when enabled; here we pin the timer contract —
+ * ticks run the shared sync runner, overlap is skipped not queued, and stop
+ * cancels + drains.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseLocationConfig } from "./config.js";
+import { startLocationAutoSync } from "./scheduler.js";
+import type { LocationSyncRuns } from "./surfaces.js";
+
+function fakeTimer() {
+  const armed: Array<{ fn: () => void; unrefd: boolean }> = [];
+  const cleared: unknown[] = [];
+  return {
+    armed,
+    cleared,
+    setInterval: (fn: () => void, _ms: number) => {
+      const handle = { fn, unrefd: false, unref() { this.unrefd = true; } };
+      armed.push(handle);
+      return handle;
+    },
+    clearInterval: (handle: unknown) => cleared.push(handle),
+  };
+}
+
+const CONFIG = parseLocationConfig({ enabled: true, sources: [{ id: "reitti" }] });
+const RUNS: LocationSyncRuns = [{ date: "2026-08-16", results: [] }];
+
+test("start arms one unref'd periodic timer whose tick runs the shared sync", async () => {
+  const timer = fakeTimer();
+  const syncs: Array<{ config: unknown; memoryDir: string }> = [];
+  const infos: string[] = [];
+  const handle = startLocationAutoSync(
+    { config: CONFIG, memoryDir: "/tmp/unused-location", setInterval: timer.setInterval, clearInterval: timer.clearInterval },
+    {
+      sync: async (deps) => {
+        syncs.push(deps);
+        return RUNS;
+      },
+      log: { info: (m) => infos.push(m), warn: (m) => infos.push(m) },
+    },
+  );
+  assert.equal(timer.armed.length, 1);
+  assert.equal(timer.armed[0]?.unrefd, true, "one-shot CLI hosts must exit naturally");
+
+  timer.armed[0]?.fn();
+  { const { promise, resolve } = Promise.withResolvers<void>(); setImmediate(resolve); await promise; }
+  assert.equal(syncs.length, 1);
+  assert.equal(syncs[0]?.memoryDir, "/tmp/unused-location");
+  assert.equal(syncs[0]?.config, CONFIG);
+
+  // First-run hook: tick() invokes the runner directly.
+  await handle.tick();
+  assert.equal(syncs.length, 2);
+
+  await handle.stop();
+  assert.equal(timer.cleared.length, 1);
+});
+
+test("an overlapping tick is skipped, not queued; failures warn and retry next tick", async () => {
+  const timer = fakeTimer();
+  let calls = 0;
+  let failFirst = true;
+  const warns: string[] = [];
+  const handle = startLocationAutoSync(
+    { config: CONFIG, memoryDir: "/tmp/unused", setInterval: timer.setInterval, clearInterval: timer.clearInterval },
+    {
+      sync: async () => {
+        calls += 1;
+        if (failFirst) {
+          failFirst = false;
+          throw new Error("ReittiApiError");
+        }
+        return RUNS;
+      },
+      log: { info: () => {}, warn: (m) => warns.push(m) },
+    },
+  );
+  timer.armed[0]?.fn(); // failing tick
+  timer.armed[0]?.fn(); // second tick while the first is still in flight
+  { const { promise, resolve } = Promise.withResolvers<void>(); setImmediate(resolve); await promise; }
+  assert.equal(calls, 1, "in-flight tick swallows the overlap");
+  assert.equal(warns.length, 1);
+  assert.match(warns[0] ?? "", /location auto-sync failed: Error/);
+
+  timer.armed[0]?.fn(); // recovers on the next tick
+  { const { promise, resolve } = Promise.withResolvers<void>(); setImmediate(resolve); await promise; }
+  assert.equal(calls, 2);
+
+  await handle.stop();
+});
+
+test("a provider failure surfaces as a warn (per-source failed status), not a throw", async () => {
+  const timer = fakeTimer();
+  const warns: string[] = [];
+  const handle = startLocationAutoSync(
+    { config: CONFIG, memoryDir: "/tmp/unused", setInterval: timer.setInterval, clearInterval: timer.clearInterval },
+    {
+      sync: async () => [
+        { date: "2026-08-16", results: [{ sourceId: "reitti", status: "failed", fetched: 0, dayWritten: false, stateSaved: false }] },
+      ],
+      log: { info: () => {}, warn: (m) => warns.push(m) },
+    },
+  );
+  timer.armed[0]?.fn();
+  { const { promise, resolve } = Promise.withResolvers<void>(); setImmediate(resolve); await promise; }
+  assert.deepEqual(warns, ["location auto-sync: one or more sources failed — retrying on the next tick"]);
+  await handle.stop();
+});

package/src/location/scheduler.ts

@@ -0,0 +1,98 @@
+/**
+ * Location auto-sync — in-process periodic day sync (issue #2047).
+ *
+ * Arms one repeating timer that runs the SAME shared surface runner
+ * (`runLocationSync`) as the CLI/MCP/HTTP surfaces over the configured
+ * `location.syncDays` window ending yesterday, so late provider uploads are
+ * picked up on the next tick. Master default-off: the caller (maintenance
+ * scheduler registration) arms this only when `location.enabled` is true and
+ * at least one source is enabled; a forced manual sync never bypasses those
+ * gates — they live inside the pipeline itself.
+ *
+ * The timer is unref'd so one-shot CLI processes exit naturally; ticks are
+ * serialized (an overlapping tick is skipped, not queued). ponytail: fixed
+ * default cadence (daily) with no per-install override — add a
+ * location.syncIntervalHours config field if installs need it.
+ */
+
+import { log } from "../logger.js";
+import { runLocationSync, type LocationSyncRuns } from "./surfaces.js";
+import type { LocationConfig } from "./types.js";
+
+export const LOCATION_SYNC_DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export interface LocationAutoSyncSettings {
+  config: LocationConfig;
+  memoryDir: string;
+  /** Tick cadence in ms; defaults to LOCATION_SYNC_DEFAULT_INTERVAL_MS. */
+  intervalMs?: number;
+  /** Clock/timer seam for tests. */
+  setInterval?: (fn: () => void, ms: number) => { unref?: () => void };
+  clearInterval?: (handle: unknown) => void;
+}
+
+export interface LocationAutoSyncDeps {
+  /** Run a sync (defaults to the shared surface runner). */
+  sync?: (deps: { config: LocationConfig; memoryDir: string }) => Promise<LocationSyncRuns>;
+  log?: { info(message: string): void; warn(message: string): void };
+}
+
+export interface LocationAutoSyncHandle {
+  /** Run one tick now (first-run hook and test seam). */
+  tick(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export function startLocationAutoSync(
+  settings: LocationAutoSyncSettings,
+  deps: LocationAutoSyncDeps = {},
+): LocationAutoSyncHandle {
+  const logger = deps.log ?? log;
+  const intervalMs = settings.intervalMs ?? LOCATION_SYNC_DEFAULT_INTERVAL_MS;
+  const setIntervalImpl = settings.setInterval ?? ((fn: () => void, ms: number) => setInterval(fn, ms));
+  const clearIntervalImpl = settings.clearInterval ?? ((handle: unknown) => clearInterval(handle as NodeJS.Timeout));
+  const sync =
+    deps.sync ??
+    ((deps: { config: LocationConfig; memoryDir: string }) =>
+      runLocationSync({ config: deps.config, memoryDir: deps.memoryDir }));
+  let inFlight: Promise<void> | null = null;
+  let stopped = false;
+  const timer = setIntervalImpl(() => {
+    if (inFlight !== null || stopped) return;
+    inFlight = (async () => {
+      try {
+        const runs = await sync({ config: settings.config, memoryDir: settings.memoryDir });
+        const failed = runs.some((run) => run.results.some((result) => result.status === "failed"));
+        if (failed) {
+          logger.warn("location auto-sync: one or more sources failed — retrying on the next tick");
+        } else {
+          logger.info(
+            `location auto-sync: refreshed ${settings.config.syncDays}-day window across ${settings.config.sources.length} source(s)`,
+          );
+        }
+      } catch (err) {
+        // An abort raised by stop() is intentional shutdown, not a failure.
+        if (err instanceof Error && err.name === "AbortError") return;
+        logger.warn(
+          `location auto-sync failed: ${err instanceof Error ? err.name : "unknown error"} — retrying on the next tick`,
+        );
+      } finally {
+        inFlight = null;
+      }
+    })();
+  }, intervalMs);
+  timer.unref?.();
+  return {
+    async tick() {
+      const runs = await sync({ config: settings.config, memoryDir: settings.memoryDir });
+      logger.info(
+        `location auto-sync tick: ${runs.length} day(s) across ${settings.config.sources.length} source(s)`,
+      );
+    },
+    async stop() {
+      stopped = true;
+      clearIntervalImpl(timer);
+      await inFlight;
+    },
+  };
+}

package/src/location/surfaces.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Location surfaces regression (issue #2047): one shared runner behind the
+ * CLI / MCP / HTTP / scheduler surfaces. These tests pin the contract the
+ * issue requires — disabled vs empty vs failure are distinct, validation is
+ * identical across surfaces, and provider registration bootstraps before
+ * status/check/sync run.
+ */
+
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseLocationConfig } from "./config.js";
+import {
+  clearLocationProviders,
+  registerLocationProvider,
+} from "./registry.js";
+import { parseLocationBackfillRange, runLocationCliCommand } from "./surfaces.js";
+import type { LocationProvider } from "./types.js";
+
+function io() {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  return {
+    stdout,
+    stderr,
+    cliIo: {
+      stdout: { write: (chunk: string) => stdout.push(chunk) },
+      stderr: { write: (chunk: string) => stderr.push(chunk) },
+    },
+  };
+}
+
+const OBSERVATION = {
+  observedAtUtc: "2026-08-16T09:00:00.000Z",
+  place: { id: "reitti:place:1", label: "Home" },
+};
+
+/** Observations only for the 2026-08-16 window; other days are valid empty days. */
+function fakeProvider(): LocationProvider {
+  return {
+    id: "reitti",
+    displayName: "Reitti",
+    verify: async () => ({ ok: true }),
+    fetchObservations: async (opts) => {
+      assert.ok(opts.startUtc < opts.endUtc, "window must be half-open");
+      const inWindow = opts.startUtc.startsWith("2026-08-16");
+      return {
+        observations: inWindow
+          ? [{ observedAtUtc: OBSERVATION.observedAtUtc, place: { ...OBSERVATION.place, kind: "other" as const } }]
+          : [],
+        nextCursor: null,
+      };
+    },
+  };
+}
+
+function enabledConfig() {
+  return parseLocationConfig({
+    enabled: true,
+    timezone: "UTC",
+    syncDays: 1,
+    sources: [{ id: "reitti" }],
+  });
+}
+
+test.afterEach(() => clearLocationProviders());
+
+test("status reports disabled master gate and unregistered provider, never an error", async () => {
+  const config = parseLocationConfig({ enabled: false, sources: [{ id: "reitti" }] });
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-status-"));
+  try {
+    const out = io();
+    const code = await runLocationCliCommand({ config, memoryDir }, ["status", "--json"], out.cliIo);
+    assert.equal(code, 0);
+    const report = JSON.parse(out.stdout.join("")) as { enabled: boolean; sources: Array<{ providerRegistered: boolean }> };
+    assert.equal(report.enabled, false);
+    assert.equal(report.sources[0]?.providerRegistered, false, "absent provider is a skip state, not an error");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("check distinguishes skip reasons from provider failures", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-check-"));
+  try {
+    // Master gate off → location-disabled skip, exit non-zero.
+    const disabled = io();
+    const disabledCode = await runLocationCliCommand(
+      { config: parseLocationConfig({ enabled: false, sources: [{ id: "reitti" }] }), memoryDir },
+      ["check"],
+      disabled.cliIo,
+    );
+    assert.match(disabled.stdout.join(""), /skipped: location-disabled/);
+    assert.equal(disabledCode, 1);
+
+    // Enabled but provider absent → provider-not-registered, distinct reason.
+    const unregistered = io();
+    const unregisteredCode = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["check"], unregistered.cliIo);
+    assert.match(unregistered.stdout.join(""), /skipped: provider-not-registered/);
+    assert.equal(unregisteredCode, 1);
+
+    // Registered healthy provider → OK, exit 0.
+    registerLocationProvider(fakeProvider());
+    const healthy = io();
+    const healthyCode = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["check"], healthy.cliIo);
+    assert.match(healthy.stdout.join(""), /reitti: OK/);
+    assert.equal(healthyCode, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("sync writes the day file through the shared runner and reports per-source results", async () => {
+  registerLocationProvider(fakeProvider());
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-sync-"));
+  try {
+    const out = io();
+    const code = await runLocationCliCommand(
+      { config: enabledConfig(), memoryDir },
+      ["sync", "--date", "2026-08-16", "--json"],
+      out.cliIo,
+    );
+    assert.equal(code, 0);
+    const payload = JSON.parse(out.stdout.join("")) as {
+      days: Array<{ date: string; results: Array<{ sourceId: string; status: string; fetched: number; dayWritten: boolean }> }>;
+    };
+    assert.equal(payload.days.length, 1);
+    assert.equal(payload.days[0]?.date, "2026-08-16");
+    assert.equal(payload.days[0]?.results[0]?.status, "synced");
+    assert.equal(payload.days[0]?.results[0]?.dayWritten, true);
+
+    // day reads back what sync wrote (same shared implementation).
+    const dayOut = io();
+    const dayCode = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["day", "2026-08-16", "--json"], dayOut.cliIo);
+    assert.equal(dayCode, 0);
+    const view = JSON.parse(dayOut.stdout.join("")) as { found: boolean; observationCount: number; sources: string[] };
+    assert.equal(view.found, true);
+    assert.equal(view.observationCount, 1, "one stored observation from the fake provider");
+    assert.deepEqual(view.sources, ["reitti"]);
+
+    // An unstored day is an explicit not-found, not an error.
+    const missing = io();
+    const missingCode = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["day", "2026-01-01"], missing.cliIo);
+    assert.equal(missingCode, 1);
+    assert.match(missing.stderr.join(""), /No stored location day/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("sync exit code reflects per-source failure", async () => {
+  const provider: LocationProvider = {
+    id: "reitti",
+    displayName: "Reitti",
+    verify: async () => ({ ok: true }),
+    fetchObservations: async () => {
+      throw new Error("ReittiApiError");
+    },
+  };
+  registerLocationProvider(provider);
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-fail-"));
+  try {
+    const out = io();
+    const code = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["sync", "--date", "2026-08-16"], out.cliIo);
+    assert.equal(code, 1);
+    assert.match(out.stdout.join(""), /reitti: failed/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("validation is strict and shared: unknown flags, bad dates, bad ranges", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-args-"));
+  try {
+    const cases: Array<[string[], RegExp]> = [
+      [["sync", "--nope"], /unknown flag '--nope'/],
+      [["sync", "--days"], /--days requires a value/],
+      [["sync", "--days", "0"], /days expects an integer from 1 to 90/],
+      [["sync", "--date", "2026-13-99"], /date is required \(YYYY-MM-DD\)/],
+      [["day", "not-a-date"], /date is required \(YYYY-MM-DD\)/],
+      [["backfill", "--from", "2026-08-10", "--to", "2026-08-01"], /--from must not be after --to/],
+      [["sync", "positional"], /sync takes flags only/],
+      [["nonsense"], /unknown command 'nonsense'/],
+    ];
+    for (const [args, pattern] of cases) {
+      const out = io();
+      const code = await runLocationCliCommand({ config: enabledConfig(), memoryDir }, args, out.cliIo);
+      assert.equal(code, 1, `${JSON.stringify(args)} exits non-zero`);
+      assert.match(out.stderr.join(""), pattern);
+    }
+
+    // Backfill range cap: 91 days rejects; 90 passes.
+    assert.throws(() => parseLocationBackfillRange("2026-05-01", "2026-07-30"), /capped at 90 days/);
+    assert.deepEqual(parseLocationBackfillRange("2026-05-02", "2026-07-30"), { endDate: "2026-07-30", days: 90 });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("backfill syncs the explicit range oldest-first; empty days are synced, not failed", async () => {
+  registerLocationProvider(fakeProvider());
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-backfill-"));
+  try {
+    const out = io();
+    const code = await runLocationCliCommand(
+      { config: enabledConfig(), memoryDir },
+      ["backfill", "--from", "2026-08-14", "--to", "2026-08-16", "--json"],
+      out.cliIo,
+    );
+    assert.equal(code, 0);
+    const payload = JSON.parse(out.stdout.join("")) as { days: Array<{ date: string; results: Array<{ status: string; fetched: number }> }> };
+    assert.deepEqual(
+      payload.days.map((d) => d.date),
+      ["2026-08-14", "2026-08-15", "2026-08-16"],
+      "oldest-first bounded range",
+    );
+    assert.deepEqual(
+      payload.days.map((d) => d.results[0]?.status),
+      ["synced", "synced", "synced"],
+      "empty days are synced, not failed",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("bare command prints usage with exit 1; help exits 0", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-location-help-"));
+  try {
+    const bare = io();
+    assert.equal(await runLocationCliCommand({ config: enabledConfig(), memoryDir }, [], bare.cliIo), 1);
+    assert.match(bare.stdout.join(""), /Usage: location/);
+    const help = io();
+    assert.equal(await runLocationCliCommand({ config: enabledConfig(), memoryDir }, ["help"], help.cliIo), 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});