@remnic/core 9.45.2 → 9.45.4

package/src/external-wiki-cli.ts

@@ -0,0 +1,92 @@
+import { type ExternalWikiRoot, searchExternalWikis } from "./external-wiki-search.js";
+
+interface ExternalWikiCliIo {
+  readonly stdout: { write(chunk: string): unknown };
+  readonly stderr: { write(chunk: string): unknown };
+}
+
+const USAGE =
+  "Usage: remnic external-wiki search <query...> [--wiki-id <id>] [--limit <1-20>] [--max-chars-per-hit <100-8000>] [--json]\n";
+
+export async function runExternalWikiCliCommand(
+  roots: readonly ExternalWikiRoot[],
+  args: readonly string[],
+  io: ExternalWikiCliIo
+): Promise<number> {
+  if (args.length === 0 || args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+    io.stdout.write(USAGE);
+    return 0;
+  }
+  if (args[0] !== "search") {
+    io.stderr.write(`external-wiki: unknown command '${args[0]}'\n${USAGE}`);
+    return 2;
+  }
+
+  let limit: number | undefined;
+  let wikiId: string | undefined;
+  let maxCharsPerHit: number | undefined;
+  let json = false;
+  const queryParts: string[] = [];
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--json") {
+      json = true;
+      continue;
+    }
+    if (argument === "--limit" || argument === "--wiki-id" || argument === "--max-chars-per-hit") {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        io.stderr.write(`external-wiki: ${argument} requires a value\n`);
+        return 2;
+      }
+      index += 1;
+      if (argument === "--wiki-id") {
+        wikiId = value.trim();
+        if (wikiId.length === 0) {
+          io.stderr.write("external-wiki: --wiki-id must not be empty\n");
+          return 2;
+        }
+        continue;
+      }
+      const parsed = Number(value);
+      const maximum = argument === "--limit" ? 20 : 8_000;
+      const minimum = argument === "--limit" ? 1 : 100;
+      if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+        io.stderr.write(`external-wiki: ${argument} must be an integer from ${minimum} to ${maximum}\n`);
+        return 2;
+      }
+      if (argument === "--limit") limit = parsed;
+      else maxCharsPerHit = parsed;
+      continue;
+    }
+    if (argument.startsWith("-")) {
+      io.stderr.write(`external-wiki: unknown option '${argument}'\n${USAGE}`);
+      return 2;
+    }
+    queryParts.push(argument);
+  }
+
+  const query = queryParts.join(" ").trim();
+  if (query.length === 0) {
+    io.stderr.write(`external-wiki: query is required\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await searchExternalWikis(roots, { query, limit, wikiId, maxCharsPerHit });
+  if (json) {
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+
+  io.stdout.write(`External wiki results for "${result.query}" (${result.count})\n`);
+  for (const hit of result.hits) {
+    const citation = hit.citations[0];
+    const location = citation ? `${citation.path}:${citation.lineStart}-${citation.lineEnd}` : hit.path;
+    io.stdout.write(`${hit.rank}. [${hit.wikiId}] ${hit.title} (${location})\n`);
+    io.stdout.write(`   ${hit.snippet.replace(/\s+/g, " ").trim()}\n`);
+  }
+  if (result.degradedWikiIds.length > 0) {
+    io.stderr.write(`external-wiki: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
+  }
+  return 0;
+}

package/src/external-wiki-collection-registration.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  type ExternalWikiCollectionRefreshTarget,
+  ExternalWikiCollectionRegistrar,
+} from "./external-wiki-collection-registration.js";
+import type { ExternalWikiCollectionRoot } from "./external-wiki-collection.js";
+
+interface TimerFixture {
+  schedule(callback: () => void, intervalMs: number): object;
+  cancel(handle: object): void;
+  callbacks: Array<() => void>;
+  intervals: number[];
+  cancelled: object[];
+}
+
+function makeTimerFixture(): TimerFixture {
+  const callbacks: Array<() => void> = [];
+  const intervals: number[] = [];
+  const cancelled: object[] = [];
+  return {
+    schedule(callback, intervalMs) {
+      callbacks.push(callback);
+      intervals.push(intervalMs);
+      return { callback };
+    },
+    cancel(handle) {
+      cancelled.push(handle);
+    },
+    callbacks,
+    intervals,
+    cancelled,
+  };
+}
+
+const roots: ExternalWikiCollectionRoot[] = [
+  {
+    id: "reading",
+    rootDir: "/tmp/wiki",
+    enabled: true,
+    pagesDir: "wiki",
+    indexInQmd: true,
+  },
+];
+
+test("registrar refreshes at startup and on its documented maintenance interval", async () => {
+  const timers = makeTimerFixture();
+  const calls: ExternalWikiCollectionRoot[][] = [];
+  const target: ExternalWikiCollectionRefreshTarget = {
+    refresh: async (configuredRoots) => {
+      calls.push([...configuredRoots]);
+      return [];
+    },
+  };
+  const registrar = new ExternalWikiCollectionRegistrar({
+    target,
+    getRoots: () => roots,
+    intervalMs: 15 * 60_000,
+    timers,
+  });
+
+  await registrar.register();
+  timers.callbacks[0]?.();
+  await registrar.waitForIdle();
+
+  assert.equal(calls.length, 2);
+  assert.deepEqual(timers.intervals, [15 * 60_000]);
+  await registrar.dispose();
+  assert.equal(timers.cancelled.length, 1);
+});
+
+test("registrar single-flights overlapping maintenance ticks", async () => {
+  const timers = makeTimerFixture();
+  let release!: () => void;
+  const blocked = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  let callCount = 0;
+  const target: ExternalWikiCollectionRefreshTarget = {
+    refresh: async () => {
+      callCount += 1;
+      if (callCount > 1) await blocked;
+      return [];
+    },
+  };
+  const registrar = new ExternalWikiCollectionRegistrar({
+    target,
+    getRoots: () => roots,
+    intervalMs: 1000,
+    timers,
+  });
+  await registrar.register();
+
+  timers.callbacks[0]?.();
+  timers.callbacks[0]?.();
+  await Promise.resolve();
+  assert.equal(callCount, 2);
+
+  release();
+  await registrar.waitForIdle();
+  await registrar.dispose();
+});
+
+test("a failed maintenance tick clears singleflight state for the next tick", async () => {
+  const timers = makeTimerFixture();
+  let callCount = 0;
+  const target: ExternalWikiCollectionRefreshTarget = {
+    refresh: async () => {
+      callCount += 1;
+      if (callCount === 2) throw new Error("backend unavailable");
+      return [];
+    },
+  };
+  const registrar = new ExternalWikiCollectionRegistrar({
+    target,
+    getRoots: () => roots,
+    intervalMs: 1000,
+    timers,
+  });
+  await registrar.register();
+
+  timers.callbacks[0]?.();
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  timers.callbacks[0]?.();
+  await registrar.waitForIdle();
+
+  assert.equal(callCount, 3);
+  await registrar.dispose();
+});
+
+test("dispose aborts and drains an in-flight refresh", async () => {
+  const timers = makeTimerFixture();
+  let observedSignal: AbortSignal | undefined;
+  let release!: () => void;
+  const blocked = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  let callCount = 0;
+  const target: ExternalWikiCollectionRefreshTarget = {
+    refresh: async (_configuredRoots, execution) => {
+      callCount += 1;
+      observedSignal = execution?.signal;
+      if (callCount > 1) await blocked;
+      return [];
+    },
+  };
+  const registrar = new ExternalWikiCollectionRegistrar({
+    target,
+    getRoots: () => roots,
+    intervalMs: 1000,
+    timers,
+  });
+  await registrar.register();
+  timers.callbacks[0]?.();
+  await Promise.resolve();
+
+  const disposing = registrar.dispose();
+  assert.equal(observedSignal?.aborted, true);
+  release();
+  await disposing;
+
+  assert.equal(timers.cancelled.length, 1);
+});

package/src/external-wiki-collection-registration.ts

@@ -0,0 +1,101 @@
+import type { ExternalWikiCollectionRoot, ExternalWikiCollectionStatus } from "./external-wiki-collection.js";
+import type { SearchExecutionOptions } from "./search/port.js";
+
+export interface ExternalWikiCollectionRefreshTarget {
+  refresh(
+    roots: readonly ExternalWikiCollectionRoot[],
+    execution?: SearchExecutionOptions
+  ): Promise<ExternalWikiCollectionStatus[]>;
+}
+
+export interface ExternalWikiCollectionTimers {
+  schedule(callback: () => void, intervalMs: number): object;
+  cancel(handle: object): void;
+}
+
+export interface ExternalWikiCollectionRegistrarOptions {
+  target: ExternalWikiCollectionRefreshTarget;
+  getRoots: () => readonly ExternalWikiCollectionRoot[];
+  intervalMs: number;
+  timers?: ExternalWikiCollectionTimers;
+}
+
+const defaultTimers: ExternalWikiCollectionTimers = {
+  schedule(callback, intervalMs) {
+    const handle = setInterval(callback, intervalMs);
+    handle.unref();
+    return handle;
+  },
+  cancel(handle) {
+    clearInterval(handle as NodeJS.Timeout);
+  },
+};
+
+export class ExternalWikiCollectionRegistrar {
+  private readonly timers: ExternalWikiCollectionTimers;
+  private timer: object | null = null;
+  private controller: AbortController | null = null;
+  private inFlight: Promise<void> | null = null;
+  private disposed = true;
+  private parentSignal: AbortSignal | null = null;
+  private parentAbortListener: (() => void) | null = null;
+
+  constructor(private readonly options: ExternalWikiCollectionRegistrarOptions) {
+    this.timers = options.timers ?? defaultTimers;
+  }
+
+  async register(signal?: AbortSignal): Promise<void> {
+    await this.dispose();
+    if (signal?.aborted) return;
+
+    this.disposed = false;
+    this.controller = new AbortController();
+    if (signal) {
+      this.parentSignal = signal;
+      this.parentAbortListener = () => this.controller?.abort();
+      signal.addEventListener("abort", this.parentAbortListener, { once: true });
+    }
+
+    await this.refreshNow();
+    if (this.disposed || this.controller.signal.aborted) return;
+    this.timer = this.timers.schedule(() => {
+      void this.refreshNow().catch(() => undefined);
+    }, this.options.intervalMs);
+  }
+
+  async refreshNow(): Promise<void> {
+    if (this.disposed || this.controller?.signal.aborted) return;
+    if (this.inFlight) return this.inFlight;
+
+    const execution = this.controller ? { signal: this.controller.signal } : undefined;
+    const running = this.options.target.refresh(this.options.getRoots(), execution).then(() => undefined);
+    this.inFlight = running;
+    const clearInFlight = () => {
+      if (this.inFlight === running) this.inFlight = null;
+    };
+    void running.then(clearInFlight, clearInFlight);
+    return running;
+  }
+
+  async waitForIdle(): Promise<void> {
+    while (this.inFlight) {
+      await this.inFlight;
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    if (this.timer) {
+      this.timers.cancel(this.timer);
+      this.timer = null;
+    }
+    this.controller?.abort();
+    if (this.parentSignal && this.parentAbortListener) {
+      this.parentSignal.removeEventListener("abort", this.parentAbortListener);
+    }
+    this.parentSignal = null;
+    this.parentAbortListener = null;
+    await this.waitForIdle();
+    this.controller = null;
+  }
+}