feat(plugins): add JavaScript plugin system with overlay panel (#303)

assets/plugins/ai-explain/main.js

@@ -0,0 +1,134 @@
+// Sends the current subtitle line, with a few lines of context, to `codex exec` and shows the
+// answer in the SubMiner plugin panel. Registers two actions: `explain` and `translate`.
+const { mkdtemp, readFile, rm } = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_SETTINGS = {
+  codexPath: 'codex',
+  model: '',
+  // Passed as -c model_reasoning_effort; low keeps answers to a few seconds. Empty uses your Codex config.
+  reasoningEffort: 'low',
+  before: 2,
+  after: 1,
+  timeoutMs: 120_000,
+  pause: true,
+  prompts: {},
+};
+
+const ACTIONS = {
+  explain: {
+    title: 'Grammar',
+    prompt:
+      'You are a Japanese tutor. Explain the line marked >>> for an intermediate learner. ' +
+      'Use the other lines only as context. Reply in English markdown: a natural translation, ' +
+      'then a bullet list of the grammar points and notable vocabulary. Be concise.',
+  },
+  translate: {
+    title: 'Translation',
+    prompt:
+      'Translate the line marked >>> into natural English. Use the other lines only as context. ' +
+      'Reply with the translation, then one short note only if the line is ambiguous.',
+  },
+};
+
+function activate(ctx) {
+  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+  for (const [name, action] of Object.entries(ACTIONS)) {
+    const prompt = settings.prompts?.[name] ?? action.prompt;
+    ctx.actions.register(name, () => ask(ctx, settings, action.title, prompt));
+  }
+}
+
+function quote(text) {
+  return text
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n');
+}
+
+// Subtitles wrap across lines; flatten each cue so the >>> marker covers all of it.
+function oneLine(text) {
+  return text
+    .split('\n')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function tail(text, lineCount) {
+  return text.trim().split('\n').slice(-lineCount).join('\n');
+}
+
+async function ask(ctx, settings, title, instructions) {
+  const { before, current, after } = ctx.subtitles.context({
+    before: settings.before,
+    after: settings.after,
+  });
+  if (!current) {
+    ctx.notify('No subtitle line to send.', { variant: 'warning' });
+    return;
+  }
+  if (settings.pause) ctx.mpv.command(['set', 'pause', 'yes']);
+
+  const header = quote(current.text);
+  const panel = ctx.ui.panel({ title, markdown: `${header}\n\n_Asking Codex..._` });
+  const prompt = [
+    instructions,
+    '',
+    'Subtitles:',
+    ...before.map((line) => oneLine(line.text)),
+    `>>> ${oneLine(current.text)}`,
+    ...after.map((line) => oneLine(line.text)),
+  ].join('\n');
+
+  // Codex runs in an empty read-only directory so any command it tries cannot touch real files.
+  const workDir = await mkdtemp(path.join(os.tmpdir(), 'subminer-ai-explain-'));
+  const answerPath = path.join(workDir, 'answer.md');
+  const args = [
+    'exec',
+    '--ephemeral',
+    '--skip-git-repo-check',
+    '--sandbox',
+    'read-only',
+    '--color',
+    'never',
+    '-C',
+    workDir,
+    '-o',
+    answerPath,
+  ];
+  if (settings.model) args.push('-m', settings.model);
+  if (settings.reasoningEffort) {
+    args.push('-c', `model_reasoning_effort=${JSON.stringify(settings.reasoningEffort)}`);
+  }
+  args.push('-');
+
+  try {
+    const result = await ctx.exec(settings.codexPath, args, {
+      stdin: prompt,
+      timeoutMs: settings.timeoutMs,
+      signal: panel.signal,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(tail(result.stderr, 6) || `codex exited with code ${result.exitCode}`);
+    }
+    const answer = (await readFile(answerPath, 'utf8')).trim();
+    panel.update({ markdown: `${header}\n\n${answer || '_Codex returned an empty answer._'}` });
+  } catch (error) {
+    // Closing the panel aborts the request; there is nobody left to show the error to.
+    if (panel.signal.aborted) return;
+    const message =
+      error?.code === 'ENOENT'
+        ? `Cannot find \`${settings.codexPath}\`. Set \`plugins.ai-explain.settings.codexPath\` to its full path.`
+        : String(error?.message ?? error);
+    ctx.log.warn(`Codex request failed: ${message}`);
+    panel.update({
+      markdown: `${header}\n\n**Codex request failed.**\n\n\`\`\`\n${message}\n\`\`\``,
+    });
+  } finally {
+    await rm(workDir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { activate };

assets/plugins/ai-explain/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "AI Explain",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "main": "main.js"
+}

assets/plugins/anki-sync/main.js

@@ -0,0 +1,61 @@
+// Runs AnkiConnect's `sync` (AnkiWeb) after you mine cards. A burst of mining becomes one sync:
+// it waits until no card has been mined for `delayMs`, and syncs right away when playback ends.
+// Also registers a `sync` action for a manual sync.
+
+const DEFAULT_SETTINGS = {
+  delayMs: 30_000,
+  syncOnEnd: true,
+  timeoutMs: 60_000,
+  notify: true,
+};
+
+const END_REASONS = new Set(['eof', 'stop', 'quit']);
+
+function activate(ctx) {
+  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+  // Cards mined since the last sync started.
+  let dirty = false;
+  let syncing = false;
+  let cancelTimer = null;
+
+  function schedule() {
+    cancelTimer?.();
+    cancelTimer = ctx.after(settings.delayMs, flush);
+  }
+
+  async function flush() {
+    cancelTimer?.();
+    cancelTimer = null;
+    // A sync already running picks up new cards when it finishes.
+    if (!dirty || syncing) return;
+    dirty = false;
+    syncing = true;
+    try {
+      await ctx.anki.invoke('sync', {}, { timeoutMs: settings.timeoutMs });
+      ctx.log.info('Synced Anki.');
+      if (settings.notify) ctx.notify('Anki synced');
+    } catch (error) {
+      ctx.log.warn(`Anki sync failed: ${error.message}`);
+      ctx.notify(`Anki sync failed: ${error.message}`, { variant: 'error' });
+    } finally {
+      syncing = false;
+      if (dirty) schedule();
+    }
+  }
+
+  ctx.anki.on('card-mined', () => {
+    dirty = true;
+    schedule();
+  });
+
+  ctx.mpv.on('end-file', ({ reason }) => {
+    if (settings.syncOnEnd && END_REASONS.has(reason)) return flush();
+  });
+
+  ctx.actions.register('sync', () => {
+    dirty = true;
+    return flush();
+  });
+}
+
+module.exports = { activate };

assets/plugins/anki-sync/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "Anki Sync",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "main": "main.js"
+}

assets/plugins/auto-jimaku/main.js

@@ -0,0 +1,51 @@
+// Opens the Jimaku subtitle search when a file starts without a Japanese subtitle track.
+// It waits a few seconds after the file loads so external subtitles mpv or SubMiner add count.
+
+const DEFAULT_SETTINGS = {
+  // Built-in action to run, e.g. `openTsukihime` or `openSubtitleSelection`.
+  action: 'openJimaku',
+  // Track `lang` codes that count as Japanese. Track titles with "Japanese" or 日本語 count too.
+  languages: ['ja', 'jp', 'jpn'],
+  delayMs: 3_000,
+  // Also check http(s) streams; Jimaku can only search by name, which streams rarely have.
+  streams: false,
+};
+
+const JAPANESE_TITLE = /japanese|日本語/i;
+
+function activate(ctx) {
+  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+  const languages = new Set(settings.languages.map((lang) => lang.toLowerCase()));
+  let cancelCheck = null;
+  let playbackId = null;
+
+  function hasJapaneseSubtitle(trackList) {
+    return trackList.some(
+      (track) =>
+        track?.type === 'sub' &&
+        (languages.has(String(track.lang ?? '').toLowerCase()) ||
+          JAPANESE_TITLE.test(String(track.title ?? ''))),
+    );
+  }
+
+  async function check(media) {
+    cancelCheck = null;
+    const trackList = await ctx.mpv.getProperty('track-list');
+    if (ctx.media.current()?.playbackId !== media.playbackId || !Array.isArray(trackList)) return;
+    if (hasJapaneseSubtitle(trackList)) return;
+    ctx.log.info(`No Japanese subtitles for ${media.path}; running ${settings.action}.`);
+    await ctx.actions.run(settings.action);
+  }
+
+  ctx.media.on('change', (media) => {
+    if (media?.playbackId === playbackId) return;
+    playbackId = media?.playbackId ?? null;
+    cancelCheck?.();
+    cancelCheck = null;
+    if (!media) return;
+    if (!settings.streams && /^[a-z]+:\/\//i.test(media.path)) return;
+    cancelCheck = ctx.after(settings.delayMs, () => check(media));
+  });
+}
+
+module.exports = { activate };

assets/plugins/auto-jimaku/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "Auto Jimaku",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "main": "main.js"
+}

assets/plugins/episode-tags/main.js

@@ -0,0 +1,110 @@
+// Tags each mined card with the show and episode it came from, e.g. `show::Frieren::S01E07`.
+// The show and episode are parsed from the file name, or from mpv's media title for streams.
+const path = require('node:path');
+
+const DEFAULT_SETTINGS = {
+  // Placeholders: {show}, {season}, {episode}, and {ep} (S01E07, or E07 without a season).
+  // A tag stops before the first `::` level whose placeholder has no value.
+  tags: ['show::{show}::{ep}'],
+  notify: false,
+};
+
+// Tried in order; the first match wins. Runs on names with brackets and dots already removed.
+const EPISODE_PATTERNS = [
+  /^(?<show>.*?)\s*S(?<season>\d{1,2})\s?E(?<episode>\d{1,4})\b/i,
+  /^(?<show>.*?)\s*(?:Season\s?(?<season>\d{1,2})\s*)?(?:Episode|Ep)\s?(?<episode>\d{1,4})\b/i,
+  /^(?<show>.*?)\s+-\s+(?<episode>\d{1,4})(?:v\d)?\b/,
+  /^(?<show>.*?)\s+(?<episode>\d{1,4})(?:v\d)?$/,
+  /^(?<show>.*?)\s*第(?<episode>\d{1,4})話/,
+];
+
+// `[Group] Show Name - 07 (1080p).mkv` -> { show: 'Show Name', season: null, episode: '07' }
+function parseMediaName(name) {
+  const cleaned = name
+    .replace(/\.[a-z0-9]{2,4}$/i, '')
+    .replace(/\[[^\]]*\]|\([^)]*\)|【[^】]*】/g, ' ')
+    .replace(/[._]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  for (const pattern of EPISODE_PATTERNS) {
+    const groups = cleaned.match(pattern)?.groups;
+    const show = groups?.show.replace(/[\s-]+$/, '');
+    if (!show) continue;
+    return { show, season: pad(groups.season), episode: pad(groups.episode) };
+  }
+  return { show: cleaned || null, season: null, episode: null };
+}
+
+function pad(number) {
+  return number ? String(Number(number)).padStart(2, '0') : null;
+}
+
+// Anki tags can't hold spaces, and a `::` in a value would add a hierarchy level.
+function tagValue(value) {
+  return value.replace(/::?/g, ' ').trim().replace(/\s+/g, '_').replace(/"/g, '');
+}
+
+function renderTag(template, values) {
+  const levels = [];
+  for (const level of template.split('::')) {
+    let missing = false;
+    const rendered = level.replace(/\{(\w+)\}/g, (_, key) => {
+      const value = values[key];
+      if (!value) missing = true;
+      return value ? tagValue(value) : '';
+    });
+    if (missing) break;
+    levels.push(rendered);
+  }
+  return levels.join('::');
+}
+
+function mediaName(mediaPath, title) {
+  // A stream URL's last segment is usually an id, so streams use the title mpv shows.
+  if (typeof mediaPath === 'string' && mediaPath && !/^[a-z]+:\/\//i.test(mediaPath)) {
+    return path.basename(mediaPath);
+  }
+  return typeof title === 'string' && title ? title : null;
+}
+
+function renderTags(templates, name) {
+  const { show, season, episode } = parseMediaName(name);
+  const ep = episode ? `${season ? `S${season}` : ''}E${episode}` : null;
+  const values = { show, season, episode, ep };
+  return [...new Set(templates.map((template) => renderTag(template, values)))].filter(Boolean);
+}
+
+function activate(ctx) {
+  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+  ctx.anki.on('card-mined', async ({ notes }) => {
+    // Notes from the same file share one addTags call.
+    const notesByName = new Map();
+    for (const { noteId, provenance } of notes) {
+      const name = mediaName(provenance?.media?.path, provenance?.media?.title);
+      if (!name) {
+        ctx.log.debug(`Note ${noteId} has no known media source; not tagging it.`);
+        continue;
+      }
+      if (!notesByName.has(name)) notesByName.set(name, new Set());
+      notesByName.get(name).add(noteId);
+    }
+
+    for (const [name, notes] of notesByName) {
+      const tags = renderTags(settings.tags, name);
+      if (tags.length === 0) {
+        ctx.log.debug(`No tags for "${name}".`);
+        continue;
+      }
+      try {
+        await ctx.anki.invoke('addTags', { notes: [...notes], tags: tags.join(' ') });
+        ctx.log.info(`Tagged ${notes.size} note(s): ${tags.join(' ')}`);
+        if (settings.notify) ctx.notify(`Tagged ${tags.join(' ')}`);
+      } catch (error) {
+        ctx.log.warn(`Tagging failed: ${error.message}`);
+        ctx.notify(`Episode tagging failed: ${error.message}`, { variant: 'error' });
+      }
+    }
+  });
+}
+
+module.exports = { activate };

assets/plugins/episode-tags/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "Episode Tags",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "main": "main.js"
+}