Enhance AniList character dictionary sync and subtitle features (#15)

src/anki-integration/field-grouping-workflow.ts

@@ -80,7 +80,7 @@ export class FieldGroupingWorkflow {
 
   async handleManual(
     originalNoteId: number,
-    newNoteId: number,
+    _newNoteId: number,
     newNoteInfo: FieldGroupingWorkflowNoteInfo,
   ): Promise<boolean> {
     const callback = await this.resolveFieldGroupingCallback();

src/anki-integration/runtime.test.ts

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
+import type { AnkiConnectConfig } from '../types';
+import { AnkiIntegrationRuntime } from './runtime';
+
+function createRuntime(
+  config: Partial<AnkiConnectConfig> = {},
+  overrides: Partial<ConstructorParameters<typeof AnkiIntegrationRuntime>[0]> = {},
+) {
+  const calls: string[] = [];
+
+  const runtime = new AnkiIntegrationRuntime({
+    initialConfig: config as AnkiConnectConfig,
+    pollingRunner: {
+      start: () => calls.push('polling:start'),
+      stop: () => calls.push('polling:stop'),
+    },
+    knownWordCache: {
+      startLifecycle: () => calls.push('known:start'),
+      stopLifecycle: () => calls.push('known:stop'),
+      clearKnownWordCacheState: () => calls.push('known:clear'),
+    },
+    proxyServerFactory: () => ({
+      start: ({ host, port, upstreamUrl }) =>
+        calls.push(`proxy:start:${host}:${port}:${upstreamUrl}`),
+      stop: () => calls.push('proxy:stop'),
+    }),
+    logInfo: () => undefined,
+    logWarn: () => undefined,
+    logError: () => undefined,
+    onConfigChanged: () => undefined,
+    ...overrides,
+  });
+
+  return { runtime, calls };
+}
+
+test('AnkiIntegrationRuntime normalizes url and proxy defaults', () => {
+  const { runtime } = createRuntime({
+    url: '  http://anki.local:8765  ',
+    proxy: {
+      enabled: true,
+      host: ' 0.0.0.0 ',
+      port: 7001,
+      upstreamUrl: '   ',
+    },
+  });
+
+  const normalized = runtime.getConfig();
+
+  assert.equal(normalized.url, 'http://anki.local:8765');
+  assert.equal(normalized.proxy?.enabled, true);
+  assert.equal(normalized.proxy?.host, '0.0.0.0');
+  assert.equal(normalized.proxy?.port, 7001);
+  assert.equal(normalized.proxy?.upstreamUrl, 'http://anki.local:8765');
+  assert.equal(
+    normalized.media?.fallbackDuration,
+    DEFAULT_ANKI_CONNECT_CONFIG.media.fallbackDuration,
+  );
+});
+
+test('AnkiIntegrationRuntime starts proxy transport when proxy mode is enabled', () => {
+  const { runtime, calls } = createRuntime({
+    proxy: {
+      enabled: true,
+      host: '127.0.0.1',
+      port: 9999,
+      upstreamUrl: 'http://upstream:8765',
+    },
+  });
+
+  runtime.start();
+
+  assert.deepEqual(calls, ['known:start', 'proxy:start:127.0.0.1:9999:http://upstream:8765']);
+});
+
+test('AnkiIntegrationRuntime switches transports and clears known words when runtime patch disables highlighting', () => {
+  const { runtime, calls } = createRuntime({
+    nPlusOne: {
+      highlightEnabled: true,
+    },
+    pollingRate: 250,
+  });
+
+  runtime.start();
+  calls.length = 0;
+
+  runtime.applyRuntimeConfigPatch({
+    nPlusOne: {
+      highlightEnabled: false,
+    },
+    proxy: {
+      enabled: true,
+      host: '127.0.0.1',
+      port: 8766,
+      upstreamUrl: 'http://127.0.0.1:8765',
+    },
+  });
+
+  assert.deepEqual(calls, [
+    'known:stop',
+    'known:clear',
+    'polling:stop',
+    'proxy:start:127.0.0.1:8766:http://127.0.0.1:8765',
+  ]);
+});

src/anki-integration/runtime.ts

@@ -0,0 +1,232 @@
+import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
+import type { AnkiConnectConfig } from '../types';
+
+export interface AnkiIntegrationRuntimeProxyServer {
+  start(options: { host: string; port: number; upstreamUrl: string }): void;
+  stop(): void;
+}
+
+interface AnkiIntegrationRuntimeDeps {
+  initialConfig: AnkiConnectConfig;
+  pollingRunner: {
+    start(): void;
+    stop(): void;
+  };
+  knownWordCache: {
+    startLifecycle(): void;
+    stopLifecycle(): void;
+    clearKnownWordCacheState(): void;
+  };
+  proxyServerFactory: () => AnkiIntegrationRuntimeProxyServer;
+  logInfo: (message: string, ...args: unknown[]) => void;
+  logWarn: (message: string, ...args: unknown[]) => void;
+  logError: (message: string, ...args: unknown[]) => void;
+  onConfigChanged?: (config: AnkiConnectConfig) => void;
+}
+
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function normalizeAnkiIntegrationConfig(config: AnkiConnectConfig): AnkiConnectConfig {
+  const resolvedUrl = trimToNonEmptyString(config.url) ?? DEFAULT_ANKI_CONNECT_CONFIG.url;
+  const proxySource =
+    config.proxy && typeof config.proxy === 'object'
+      ? (config.proxy as NonNullable<AnkiConnectConfig['proxy']>)
+      : {};
+  const normalizedProxyPort =
+    typeof proxySource.port === 'number' &&
+    Number.isInteger(proxySource.port) &&
+    proxySource.port >= 1 &&
+    proxySource.port <= 65535
+      ? proxySource.port
+      : DEFAULT_ANKI_CONNECT_CONFIG.proxy?.port;
+  const normalizedProxyHost =
+    trimToNonEmptyString(proxySource.host) ?? DEFAULT_ANKI_CONNECT_CONFIG.proxy?.host;
+  const normalizedProxyUpstreamUrl = trimToNonEmptyString(proxySource.upstreamUrl) ?? resolvedUrl;
+
+  return {
+    ...DEFAULT_ANKI_CONNECT_CONFIG,
+    ...config,
+    url: resolvedUrl,
+    fields: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.fields,
+      ...(config.fields ?? {}),
+    },
+    proxy: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.proxy,
+      ...(config.proxy ?? {}),
+      enabled: proxySource.enabled === true,
+      host: normalizedProxyHost,
+      port: normalizedProxyPort,
+      upstreamUrl: normalizedProxyUpstreamUrl,
+    },
+    ai: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.ai,
+      ...(config.openRouter ?? {}),
+      ...(config.ai ?? {}),
+    },
+    media: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.media,
+      ...(config.media ?? {}),
+    },
+    behavior: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.behavior,
+      ...(config.behavior ?? {}),
+    },
+    metadata: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.metadata,
+      ...(config.metadata ?? {}),
+    },
+    isLapis: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.isLapis,
+      ...(config.isLapis ?? {}),
+    },
+    isKiku: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.isKiku,
+      ...(config.isKiku ?? {}),
+    },
+  } as AnkiConnectConfig;
+}
+
+export class AnkiIntegrationRuntime {
+  private config: AnkiConnectConfig;
+  private proxyServer: AnkiIntegrationRuntimeProxyServer | null = null;
+  private started = false;
+
+  constructor(private readonly deps: AnkiIntegrationRuntimeDeps) {
+    this.config = normalizeAnkiIntegrationConfig(deps.initialConfig);
+  }
+
+  getConfig(): AnkiConnectConfig {
+    return this.config;
+  }
+
+  start(): void {
+    if (this.started) {
+      this.stop();
+    }
+
+    this.deps.knownWordCache.startLifecycle();
+    this.startTransport();
+    this.started = true;
+  }
+
+  stop(): void {
+    this.stopTransport();
+    this.deps.knownWordCache.stopLifecycle();
+    this.started = false;
+    this.deps.logInfo('Stopped AnkiConnect integration');
+  }
+
+  applyRuntimeConfigPatch(patch: Partial<AnkiConnectConfig>): void {
+    const wasKnownWordCacheEnabled = this.config.nPlusOne?.highlightEnabled === true;
+    const previousTransportKey = this.getTransportConfigKey(this.config);
+
+    const mergedConfig: AnkiConnectConfig = {
+      ...this.config,
+      ...patch,
+      nPlusOne:
+        patch.nPlusOne !== undefined
+          ? {
+              ...(this.config.nPlusOne ?? DEFAULT_ANKI_CONNECT_CONFIG.nPlusOne),
+              ...patch.nPlusOne,
+            }
+          : this.config.nPlusOne,
+      fields:
+        patch.fields !== undefined
+          ? { ...this.config.fields, ...patch.fields }
+          : this.config.fields,
+      media:
+        patch.media !== undefined ? { ...this.config.media, ...patch.media } : this.config.media,
+      behavior:
+        patch.behavior !== undefined
+          ? { ...this.config.behavior, ...patch.behavior }
+          : this.config.behavior,
+      proxy:
+        patch.proxy !== undefined ? { ...this.config.proxy, ...patch.proxy } : this.config.proxy,
+      metadata:
+        patch.metadata !== undefined
+          ? { ...this.config.metadata, ...patch.metadata }
+          : this.config.metadata,
+      isLapis:
+        patch.isLapis !== undefined
+          ? { ...this.config.isLapis, ...patch.isLapis }
+          : this.config.isLapis,
+      isKiku:
+        patch.isKiku !== undefined
+          ? { ...this.config.isKiku, ...patch.isKiku }
+          : this.config.isKiku,
+    };
+    this.config = normalizeAnkiIntegrationConfig(mergedConfig);
+    this.deps.onConfigChanged?.(this.config);
+
+    if (wasKnownWordCacheEnabled && this.config.nPlusOne?.highlightEnabled === false) {
+      this.deps.knownWordCache.stopLifecycle();
+      this.deps.knownWordCache.clearKnownWordCacheState();
+    } else {
+      this.deps.knownWordCache.startLifecycle();
+    }
+
+    const nextTransportKey = this.getTransportConfigKey(this.config);
+    if (this.started && previousTransportKey !== nextTransportKey) {
+      this.stopTransport();
+      this.startTransport();
+    }
+  }
+
+  getOrCreateProxyServer(): AnkiIntegrationRuntimeProxyServer {
+    if (!this.proxyServer) {
+      this.proxyServer = this.deps.proxyServerFactory();
+    }
+    return this.proxyServer;
+  }
+
+  private isProxyTransportEnabled(config: AnkiConnectConfig = this.config): boolean {
+    return config.proxy?.enabled === true;
+  }
+
+  private getTransportConfigKey(config: AnkiConnectConfig = this.config): string {
+    if (this.isProxyTransportEnabled(config)) {
+      return [
+        'proxy',
+        config.proxy?.host ?? '',
+        String(config.proxy?.port ?? ''),
+        config.proxy?.upstreamUrl ?? '',
+      ].join(':');
+    }
+    return ['polling', String(config.pollingRate ?? DEFAULT_ANKI_CONNECT_CONFIG.pollingRate)].join(
+      ':',
+    );
+  }
+
+  private startTransport(): void {
+    if (this.isProxyTransportEnabled()) {
+      const proxyHost = this.config.proxy?.host ?? '127.0.0.1';
+      const proxyPort = this.config.proxy?.port ?? 8766;
+      const upstreamUrl = this.config.proxy?.upstreamUrl ?? this.config.url ?? '';
+      this.getOrCreateProxyServer().start({
+        host: proxyHost,
+        port: proxyPort,
+        upstreamUrl,
+      });
+      this.deps.logInfo(
+        `Starting AnkiConnect integration with local proxy: http://${proxyHost}:${proxyPort} -> ${upstreamUrl}`,
+      );
+      return;
+    }
+
+    this.deps.logInfo(
+      'Starting AnkiConnect integration with polling rate:',
+      this.config.pollingRate,
+    );
+    this.deps.pollingRunner.start();
+  }
+
+  private stopTransport(): void {
+    this.deps.pollingRunner.stop();
+    this.proxyServer?.stop();
+  }
+}