feat(macos): configuration window + curl-backed macOS updater (#71)

This commit is contained in:
2026-05-17 02:23:44 -07:00
committed by GitHub
parent 6ca5cede3e
commit e84674e3b5
100 changed files with 13890 additions and 235 deletions
@@ -1,6 +1,7 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { ResolvedConfig } from '../../types/config';
import {
CONFIG_OPTION_REGISTRY,
CONFIG_TEMPLATE_SECTIONS,
@@ -13,6 +14,77 @@ import { buildImmersionConfigOptionRegistry } from './options-immersion';
import { buildIntegrationConfigOptionRegistry } from './options-integrations';
import { buildSubtitleConfigOptionRegistry } from './options-subtitle';
function collectConfigLeafPaths(config: ResolvedConfig): string[] {
const leaves: string[] = [];
const visit = (value: unknown, prefix: string): void => {
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
leaves.push(prefix);
return;
}
const entries = Object.entries(value as Record<string, unknown>);
if (entries.length === 0) {
leaves.push(prefix);
return;
}
for (const [key, child] of entries) {
visit(child, prefix ? `${prefix}.${key}` : key);
}
};
visit(config, '');
return leaves;
}
// DEFAULT_CONFIG leaves that intentionally do not have a curated
// CONFIG_OPTION_REGISTRY entry. The generated config.example.jsonc still
// includes these paths, but their inline comments fall back to an auto-
// humanized key name instead of a written description.
//
// Current intentional gaps:
// - subtitleStyle.*: thin wrappers around standard CSS properties; the
// CSS reference is the canonical documentation surface.
// - keybindings: an array of {key, command} objects, documented at the
// section level via CONFIG_TEMPLATE_SECTIONS rather than per-leaf.
//
// New leaves added to DEFAULT_CONFIG should prefer a registry entry over
// an allowlist entry. Only allowlist a path when the registry is genuinely
// the wrong surface for it.
const UNDOCUMENTED_LEAVES: ReadonlySet<string> = new Set([
'keybindings',
'subtitleStyle.backdropFilter',
'subtitleStyle.backgroundColor',
'subtitleStyle.fontColor',
'subtitleStyle.fontFamily',
'subtitleStyle.fontKerning',
'subtitleStyle.fontSize',
'subtitleStyle.fontStyle',
'subtitleStyle.fontWeight',
'subtitleStyle.jlptColors.N1',
'subtitleStyle.jlptColors.N2',
'subtitleStyle.jlptColors.N3',
'subtitleStyle.jlptColors.N4',
'subtitleStyle.jlptColors.N5',
'subtitleStyle.knownWordColor',
'subtitleStyle.letterSpacing',
'subtitleStyle.lineHeight',
'subtitleStyle.nPlusOneColor',
'subtitleStyle.secondary.backdropFilter',
'subtitleStyle.secondary.backgroundColor',
'subtitleStyle.secondary.fontColor',
'subtitleStyle.secondary.fontFamily',
'subtitleStyle.secondary.fontKerning',
'subtitleStyle.secondary.fontSize',
'subtitleStyle.secondary.fontStyle',
'subtitleStyle.secondary.fontWeight',
'subtitleStyle.secondary.letterSpacing',
'subtitleStyle.secondary.lineHeight',
'subtitleStyle.secondary.textRendering',
'subtitleStyle.secondary.textShadow',
'subtitleStyle.secondary.wordSpacing',
'subtitleStyle.textRendering',
'subtitleStyle.textShadow',
'subtitleStyle.wordSpacing',
]);
test('config option registry includes critical paths and has unique entries', () => {
const paths = CONFIG_OPTION_REGISTRY.map((entry) => entry.path);
@@ -40,6 +112,35 @@ test('config option registry includes critical paths and has unique entries', ()
assert.equal(new Set(paths).size, paths.length);
});
test('every DEFAULT_CONFIG leaf is in CONFIG_OPTION_REGISTRY or UNDOCUMENTED_LEAVES', () => {
const registryPaths = new Set(CONFIG_OPTION_REGISTRY.map((entry) => entry.path));
const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
const missing = leaves
.filter((path) => !registryPaths.has(path) && !UNDOCUMENTED_LEAVES.has(path))
.sort();
assert.deepEqual(
missing,
[],
`Add CONFIG_OPTION_REGISTRY entries (preferred) or add to UNDOCUMENTED_LEAVES allowlist: ${missing.join(', ')}`,
);
const stale = [...UNDOCUMENTED_LEAVES].filter((path) => registryPaths.has(path)).sort();
assert.deepEqual(
stale,
[],
`Remove from UNDOCUMENTED_LEAVES (now covered by CONFIG_OPTION_REGISTRY): ${stale.join(', ')}`,
);
const leafSet = new Set(leaves);
const orphaned = [...UNDOCUMENTED_LEAVES].filter((path) => !leafSet.has(path)).sort();
assert.deepEqual(
orphaned,
[],
`Remove from UNDOCUMENTED_LEAVES (no longer a DEFAULT_CONFIG leaf): ${orphaned.join(', ')}`,
);
});
test('config template sections include expected domains and unique keys', () => {
const keys = CONFIG_TEMPLATE_SECTIONS.map((section) => section.key);
const requiredKeys: (typeof keys)[number][] = [
+168
View File
@@ -322,6 +322,46 @@ export function buildCoreConfigOptionRegistry(
defaultValue: defaultConfig.texthooker.launchAtStartup,
description: 'Launch texthooker server automatically when SubMiner starts.',
},
{
path: 'texthooker.openBrowser',
kind: 'boolean',
defaultValue: defaultConfig.texthooker.openBrowser,
description: 'Open the texthooker page in the default browser when the server starts.',
},
{
path: 'subtitlePosition.yPercent',
kind: 'number',
defaultValue: defaultConfig.subtitlePosition.yPercent,
description:
'Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.',
},
{
path: 'auto_start_overlay',
kind: 'boolean',
defaultValue: defaultConfig.auto_start_overlay,
description: 'Auto-start the subtitle overlay window when SubMiner launches.',
},
{
path: 'secondarySub.secondarySubLanguages',
kind: 'array',
defaultValue: defaultConfig.secondarySub.secondarySubLanguages,
description:
'Language code priority list used to auto-select a secondary subtitle track when available.',
},
{
path: 'secondarySub.autoLoadSecondarySub',
kind: 'boolean',
defaultValue: defaultConfig.secondarySub.autoLoadSecondarySub,
description:
'Automatically load a matching secondary subtitle when the primary subtitle loads.',
},
{
path: 'secondarySub.defaultMode',
kind: 'enum',
enumValues: ['hidden', 'visible', 'hover'],
defaultValue: defaultConfig.secondarySub.defaultMode,
description: 'Default visibility mode for the secondary subtitle bar.',
},
{
path: 'websocket.enabled',
kind: 'enum',
@@ -360,6 +400,27 @@ export function buildCoreConfigOptionRegistry(
defaultValue: defaultConfig.subsync.replace,
description: 'Replace the active subtitle file when sync completes.',
},
{
path: 'subsync.alass_path',
kind: 'string',
defaultValue: defaultConfig.subsync.alass_path,
description:
'Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.',
},
{
path: 'subsync.ffsubsync_path',
kind: 'string',
defaultValue: defaultConfig.subsync.ffsubsync_path,
description:
'Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.',
},
{
path: 'subsync.ffmpeg_path',
kind: 'string',
defaultValue: defaultConfig.subsync.ffmpeg_path,
description:
'Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.',
},
{
path: 'startupWarmups.lowPowerMode',
kind: 'boolean',
@@ -422,5 +483,112 @@ export function buildCoreConfigOptionRegistry(
defaultValue: defaultConfig.shortcuts.multiCopyTimeoutMs,
description: 'Timeout for multi-copy/mine modes.',
},
{
path: 'shortcuts.toggleVisibleOverlayGlobal',
kind: 'string',
defaultValue: defaultConfig.shortcuts.toggleVisibleOverlayGlobal,
description:
'Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.',
},
{
path: 'shortcuts.copySubtitle',
kind: 'string',
defaultValue: defaultConfig.shortcuts.copySubtitle,
description: 'Accelerator that copies the current subtitle line to the clipboard.',
},
{
path: 'shortcuts.copySubtitleMultiple',
kind: 'string',
defaultValue: defaultConfig.shortcuts.copySubtitleMultiple,
description:
'Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.',
},
{
path: 'shortcuts.updateLastCardFromClipboard',
kind: 'string',
defaultValue: defaultConfig.shortcuts.updateLastCardFromClipboard,
description:
'Accelerator that updates the last mined Anki card using the current clipboard contents.',
},
{
path: 'shortcuts.triggerFieldGrouping',
kind: 'string',
defaultValue: defaultConfig.shortcuts.triggerFieldGrouping,
description: 'Accelerator that triggers Kiku field grouping on duplicate cards.',
},
{
path: 'shortcuts.triggerSubsync',
kind: 'string',
defaultValue: defaultConfig.shortcuts.triggerSubsync,
description: 'Accelerator that triggers subsync against the active subtitle file.',
},
{
path: 'shortcuts.mineSentence',
kind: 'string',
defaultValue: defaultConfig.shortcuts.mineSentence,
description: 'Accelerator that mines the current sentence as a new Anki card.',
},
{
path: 'shortcuts.mineSentenceMultiple',
kind: 'string',
defaultValue: defaultConfig.shortcuts.mineSentenceMultiple,
description:
'Accelerator that mines consecutive sentences while the multi-mine window stays open.',
},
{
path: 'shortcuts.toggleSecondarySub',
kind: 'string',
defaultValue: defaultConfig.shortcuts.toggleSecondarySub,
description: 'Accelerator that toggles the secondary subtitle bar visibility.',
},
{
path: 'shortcuts.markAudioCard',
kind: 'string',
defaultValue: defaultConfig.shortcuts.markAudioCard,
description: 'Accelerator that marks the last mined card as an audio card.',
},
{
path: 'shortcuts.openCharacterDictionary',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openCharacterDictionary,
description: 'Accelerator that opens the character dictionary modal.',
},
{
path: 'shortcuts.openRuntimeOptions',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openRuntimeOptions,
description: 'Accelerator that opens the runtime options modal.',
},
{
path: 'shortcuts.openJimaku',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openJimaku,
description: 'Accelerator that opens the Jimaku subtitle search modal.',
},
{
path: 'shortcuts.openSessionHelp',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openSessionHelp,
description: 'Accelerator that opens the session help / keybinding cheatsheet.',
},
{
path: 'shortcuts.openControllerSelect',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openControllerSelect,
description: 'Accelerator that opens the controller selection and learn-mode modal.',
},
{
path: 'shortcuts.openControllerDebug',
kind: 'string',
defaultValue: defaultConfig.shortcuts.openControllerDebug,
description:
'Accelerator that opens the controller debug modal with live axis/button readouts.',
},
{
path: 'shortcuts.toggleSubtitleSidebar',
kind: 'string',
defaultValue: defaultConfig.shortcuts.toggleSubtitleSidebar,
description: 'Accelerator that toggles the subtitle sidebar visibility.',
},
];
}
@@ -15,6 +15,12 @@ export function buildIntegrationConfigOptionRegistry(
defaultValue: defaultConfig.ankiConnect.enabled,
description: 'Enable AnkiConnect integration.',
},
{
path: 'ankiConnect.url',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.url,
description: 'Base URL of the AnkiConnect HTTP server.',
},
{
path: 'ankiConnect.pollingRate',
kind: 'number',
@@ -58,6 +64,37 @@ export function buildIntegrationConfigOptionRegistry(
defaultValue: defaultConfig.ankiConnect.fields.word,
description: 'Card field for the mined word or expression text.',
},
{
path: 'ankiConnect.fields.audio',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.fields.audio,
description: 'Card field that receives generated sentence audio.',
},
{
path: 'ankiConnect.fields.image',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.fields.image,
description: 'Card field that receives the captured screenshot or animated image.',
},
{
path: 'ankiConnect.fields.sentence',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.fields.sentence,
description: 'Card field that receives the source sentence text.',
},
{
path: 'ankiConnect.fields.miscInfo',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.fields.miscInfo,
description:
'Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).',
},
{
path: 'ankiConnect.fields.translation',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.fields.translation,
description: 'Card field that receives the current selection or translated text.',
},
{
path: 'ankiConnect.ai.enabled',
kind: 'boolean',
@@ -83,6 +120,41 @@ export function buildIntegrationConfigOptionRegistry(
description: 'Automatically update newly added cards.',
runtime: runtimeOptionById.get('anki.autoUpdateNewCards'),
},
{
path: 'ankiConnect.behavior.overwriteAudio',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.behavior.overwriteAudio,
description:
'When updating an existing card, overwrite the audio field instead of skipping it.',
},
{
path: 'ankiConnect.behavior.overwriteImage',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.behavior.overwriteImage,
description:
'When updating an existing card, overwrite the image field instead of skipping it.',
},
{
path: 'ankiConnect.behavior.mediaInsertMode',
kind: 'enum',
enumValues: ['append', 'prepend'],
defaultValue: defaultConfig.ankiConnect.behavior.mediaInsertMode,
description:
'Whether new media is appended after or prepended before existing field contents on update.',
},
{
path: 'ankiConnect.behavior.highlightWord',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.behavior.highlightWord,
description: 'Bold the mined word inside the sentence field on the saved Anki card.',
},
{
path: 'ankiConnect.behavior.notificationType',
kind: 'enum',
enumValues: ['osd', 'system', 'both', 'none'],
defaultValue: defaultConfig.ankiConnect.behavior.notificationType,
description: 'Notification surface used to announce mining and update outcomes.',
},
{
path: 'ankiConnect.media.syncAnimatedImageToWordAudio',
kind: 'boolean',
@@ -90,6 +162,97 @@ export function buildIntegrationConfigOptionRegistry(
description:
'For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio.',
},
{
path: 'ankiConnect.media.generateAudio',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.media.generateAudio,
description: 'Generate sentence audio for mined cards.',
},
{
path: 'ankiConnect.media.generateImage',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.media.generateImage,
description: 'Generate screenshot or animated image for mined cards.',
},
{
path: 'ankiConnect.media.imageType',
kind: 'enum',
enumValues: ['static', 'avif'],
defaultValue: defaultConfig.ankiConnect.media.imageType,
description:
'Image capture type: "static" for a single still frame, "avif" for an animated AVIF.',
},
{
path: 'ankiConnect.media.imageFormat',
kind: 'enum',
enumValues: ['jpg', 'png', 'webp'],
defaultValue: defaultConfig.ankiConnect.media.imageFormat,
description: 'Encoding format used when imageType is "static".',
},
{
path: 'ankiConnect.media.imageQuality',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.imageQuality,
description: 'Quality (0-100) used for lossy static image encoders.',
},
{
path: 'ankiConnect.media.imageMaxWidth',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.imageMaxWidth,
description:
'Optional maximum width for static images. Leave unset to preserve the source resolution.',
},
{
path: 'ankiConnect.media.imageMaxHeight',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.imageMaxHeight,
description:
'Optional maximum height for static images. Leave unset to preserve the source resolution.',
},
{
path: 'ankiConnect.media.animatedFps',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.animatedFps,
description: 'Target frame rate for animated AVIF captures.',
},
{
path: 'ankiConnect.media.animatedMaxWidth',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.animatedMaxWidth,
description: 'Maximum width applied to animated AVIF captures.',
},
{
path: 'ankiConnect.media.animatedMaxHeight',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.animatedMaxHeight,
description:
'Optional maximum height for animated AVIF captures. Leave unset to preserve aspect ratio.',
},
{
path: 'ankiConnect.media.animatedCrf',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.animatedCrf,
description:
'Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.',
},
{
path: 'ankiConnect.media.audioPadding',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.audioPadding,
description: 'Seconds of padding appended to both ends of generated sentence audio.',
},
{
path: 'ankiConnect.media.fallbackDuration',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.fallbackDuration,
description: 'Fallback clip duration in seconds when subtitle timing data is unavailable.',
},
{
path: 'ankiConnect.media.maxMediaDuration',
kind: 'number',
defaultValue: defaultConfig.ankiConnect.media.maxMediaDuration,
description: 'Maximum allowed media clip duration in seconds.',
},
{
path: 'ankiConnect.knownWords.matchMode',
kind: 'enum',
@@ -148,6 +311,44 @@ export function buildIntegrationConfigOptionRegistry(
description: 'Kiku duplicate-card field grouping mode.',
runtime: runtimeOptionById.get('anki.kikuFieldGrouping'),
},
{
path: 'ankiConnect.isKiku.enabled',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.isKiku.enabled,
description: 'Enable Kiku-specific mining behaviors (duplicate handling, field grouping).',
},
{
path: 'ankiConnect.isKiku.deleteDuplicateInAuto',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.isKiku.deleteDuplicateInAuto,
description:
'When Kiku field grouping is "auto", delete the duplicate source card after grouping completes.',
},
{
path: 'ankiConnect.isLapis.enabled',
kind: 'boolean',
defaultValue: defaultConfig.ankiConnect.isLapis.enabled,
description: 'Enable Lapis-specific mining behaviors and sentence card model targeting.',
},
{
path: 'ankiConnect.isLapis.sentenceCardModel',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.isLapis.sentenceCardModel,
description: 'Note type name used by Lapis sentence cards.',
},
{
path: 'ankiConnect.metadata.pattern',
kind: 'string',
defaultValue: defaultConfig.ankiConnect.metadata.pattern,
description:
'Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).',
},
{
path: 'jimaku.apiBaseUrl',
kind: 'string',
defaultValue: defaultConfig.jimaku.apiBaseUrl,
description: 'Base URL of the Jimaku subtitle search API.',
},
{
path: 'jimaku.languagePreference',
kind: 'enum',
@@ -277,6 +478,26 @@ export function buildIntegrationConfigOptionRegistry(
defaultValue: defaultConfig.jellyfin.username,
description: 'Default Jellyfin username used during CLI login.',
},
{
path: 'jellyfin.deviceId',
kind: 'string',
defaultValue: defaultConfig.jellyfin.deviceId,
description:
'Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.',
},
{
path: 'jellyfin.clientName',
kind: 'string',
defaultValue: defaultConfig.jellyfin.clientName,
description: 'Client name sent on the Jellyfin authentication handshake; primarily internal.',
},
{
path: 'jellyfin.clientVersion',
kind: 'string',
defaultValue: defaultConfig.jellyfin.clientVersion,
description:
'Client version sent on the Jellyfin authentication handshake; primarily internal.',
},
{
path: 'jellyfin.defaultLibraryId',
kind: 'string',
@@ -387,6 +608,18 @@ export function buildIntegrationConfigOptionRegistry(
defaultValue: defaultConfig.ai.baseUrl,
description: 'Base URL for the shared OpenAI-compatible AI provider.',
},
{
path: 'ai.model',
kind: 'string',
defaultValue: defaultConfig.ai.model,
description: 'Default model identifier requested from the shared AI provider.',
},
{
path: 'ai.systemPrompt',
kind: 'string',
defaultValue: defaultConfig.ai.systemPrompt,
description: 'Default system prompt sent with shared AI provider requests.',
},
{
path: 'ai.requestTimeoutMs',
kind: 'number',