refactor(launcher): split CLI flow into command modules

Isolate process-side effects behind adapter seams and keep wrapper behavior stable while improving command-level testability.

launcher/commands/app-command.ts

@@ -0,0 +1,20 @@
+import { launchTexthookerOnly, runAppCommandWithInherit } from '../mpv.js';
+import type { LauncherCommandContext } from './context.js';
+
+export function runAppPassthroughCommand(context: LauncherCommandContext): boolean {
+  const { args, appPath } = context;
+  if (!args.appPassthrough || !appPath) {
+    return false;
+  }
+  runAppCommandWithInherit(appPath, args.appArgs);
+  return true;
+}
+
+export function runTexthookerCommand(context: LauncherCommandContext): boolean {
+  const { args, appPath } = context;
+  if (!args.texthookerOnly || !appPath) {
+    return false;
+  }
+  launchTexthookerOnly(appPath, args);
+  return true;
+}

launcher/commands/command-modules.test.ts

@@ -0,0 +1,90 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgs } from '../config.js';
+import type { ProcessAdapter } from '../process-adapter.js';
+import type { LauncherCommandContext } from './context.js';
+import { runConfigCommand } from './config-command.js';
+import { runDoctorCommand } from './doctor-command.js';
+import { runMpvPreAppCommand } from './mpv-command.js';
+
+class ExitSignal extends Error {
+  code: number;
+
+  constructor(code: number) {
+    super(`exit:${code}`);
+    this.code = code;
+  }
+}
+
+function createContext(overrides: Partial<LauncherCommandContext> = {}): LauncherCommandContext {
+  const args = parseArgs([], 'subminer', {});
+  const adapter: ProcessAdapter = {
+    platform: () => 'linux',
+    onSignal: () => {},
+    writeStdout: () => {},
+    exit: (code) => {
+      throw new ExitSignal(code);
+    },
+    setExitCode: () => {},
+  };
+
+  return {
+    args,
+    scriptPath: '/tmp/subminer',
+    scriptName: 'subminer',
+    mpvSocketPath: '/tmp/subminer.sock',
+    appPath: '/tmp/subminer.app',
+    launcherJellyfinConfig: {},
+    processAdapter: adapter,
+    ...overrides,
+  };
+}
+
+test('config command writes newline-terminated path via process adapter', () => {
+  const writes: string[] = [];
+  const context = createContext();
+  context.args.configPath = true;
+  context.processAdapter = {
+    ...context.processAdapter,
+    writeStdout: (text) => writes.push(text),
+  };
+
+  const handled = runConfigCommand(context, {
+    existsSync: () => true,
+    readFileSync: () => '',
+    resolveMainConfigPath: () => '/tmp/SubMiner/config.jsonc',
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(writes, ['/tmp/SubMiner/config.jsonc\n']);
+});
+
+test('doctor command exits non-zero for missing hard dependencies', () => {
+  const context = createContext({ appPath: null });
+  context.args.doctor = true;
+
+  assert.throws(
+    () =>
+      runDoctorCommand(context, {
+        commandExists: () => false,
+        configExists: () => true,
+        resolveMainConfigPath: () => '/tmp/SubMiner/config.jsonc',
+      }),
+    (error: unknown) => error instanceof ExitSignal && error.code === 1,
+  );
+});
+
+test('mpv pre-app command exits non-zero when socket is not ready', async () => {
+  const context = createContext();
+  context.args.mpvStatus = true;
+
+  await assert.rejects(
+    async () => {
+      await runMpvPreAppCommand(context, {
+        waitForUnixSocketReady: async () => false,
+        launchMpvIdleDetached: async () => {},
+      });
+    },
+    (error: unknown) => error instanceof ExitSignal && error.code === 1,
+  );
+});

launcher/commands/config-command.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import { fail } from '../log.js';
+import { resolveMainConfigPath } from '../config-path.js';
+import type { LauncherCommandContext } from './context.js';
+
+interface ConfigCommandDeps {
+  existsSync(path: string): boolean;
+  readFileSync(path: string, encoding: BufferEncoding): string;
+  resolveMainConfigPath(): string;
+}
+
+const defaultDeps: ConfigCommandDeps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  resolveMainConfigPath,
+};
+
+export function runConfigCommand(
+  context: LauncherCommandContext,
+  deps: ConfigCommandDeps = defaultDeps,
+): boolean {
+  const { args, processAdapter } = context;
+  if (args.configPath) {
+    processAdapter.writeStdout(`${deps.resolveMainConfigPath()}\n`);
+    return true;
+  }
+
+  if (!args.configShow) {
+    return false;
+  }
+
+  const configPath = deps.resolveMainConfigPath();
+  if (!deps.existsSync(configPath)) {
+    fail(`Config file not found: ${configPath}`);
+  }
+
+  const contents = deps.readFileSync(configPath, 'utf8');
+  processAdapter.writeStdout(contents);
+  if (!contents.endsWith('\n')) {
+    processAdapter.writeStdout('\n');
+  }
+  return true;
+}

launcher/commands/context.ts

@@ -0,0 +1,12 @@
+import type { Args, LauncherJellyfinConfig } from '../types.js';
+import type { ProcessAdapter } from '../process-adapter.js';
+
+export interface LauncherCommandContext {
+  args: Args;
+  scriptPath: string;
+  scriptName: string;
+  mpvSocketPath: string;
+  appPath: string | null;
+  launcherJellyfinConfig: LauncherJellyfinConfig;
+  processAdapter: ProcessAdapter;
+}

launcher/commands/doctor-command.ts

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import { log } from '../log.js';
+import { commandExists } from '../util.js';
+import { resolveMainConfigPath } from '../config-path.js';
+import type { LauncherCommandContext } from './context.js';
+
+interface DoctorCommandDeps {
+  commandExists(command: string): boolean;
+  configExists(path: string): boolean;
+  resolveMainConfigPath(): string;
+}
+
+const defaultDeps: DoctorCommandDeps = {
+  commandExists,
+  configExists: fs.existsSync,
+  resolveMainConfigPath,
+};
+
+export function runDoctorCommand(
+  context: LauncherCommandContext,
+  deps: DoctorCommandDeps = defaultDeps,
+): boolean {
+  const { args, appPath, mpvSocketPath, processAdapter } = context;
+  if (!args.doctor) {
+    return false;
+  }
+
+  const configPath = deps.resolveMainConfigPath();
+  const mpvFound = deps.commandExists('mpv');
+  const checks: Array<{ label: string; ok: boolean; detail: string }> = [
+    {
+      label: 'app binary',
+      ok: Boolean(appPath),
+      detail: appPath || 'not found (set SUBMINER_APPIMAGE_PATH)',
+    },
+    {
+      label: 'mpv',
+      ok: mpvFound,
+      detail: mpvFound ? 'found' : 'missing',
+    },
+    {
+      label: 'yt-dlp',
+      ok: deps.commandExists('yt-dlp'),
+      detail: deps.commandExists('yt-dlp') ? 'found' : 'missing (optional unless YouTube URLs)',
+    },
+    {
+      label: 'ffmpeg',
+      ok: deps.commandExists('ffmpeg'),
+      detail: deps.commandExists('ffmpeg')
+        ? 'found'
+        : 'missing (optional unless subtitle generation)',
+    },
+    {
+      label: 'fzf',
+      ok: deps.commandExists('fzf'),
+      detail: deps.commandExists('fzf') ? 'found' : 'missing (optional if using rofi)',
+    },
+    {
+      label: 'rofi',
+      ok: deps.commandExists('rofi'),
+      detail: deps.commandExists('rofi') ? 'found' : 'missing (optional if using fzf)',
+    },
+    {
+      label: 'config',
+      ok: deps.configExists(configPath),
+      detail: configPath,
+    },
+    {
+      label: 'mpv socket path',
+      ok: true,
+      detail: mpvSocketPath,
+    },
+  ];
+
+  const hasHardFailure = checks.some((entry) =>
+    entry.label === 'app binary' || entry.label === 'mpv' ? !entry.ok : false,
+  );
+
+  for (const check of checks) {
+    log(check.ok ? 'info' : 'warn', args.logLevel, `[doctor] ${check.label}: ${check.detail}`);
+  }
+
+  processAdapter.exit(hasHardFailure ? 1 : 0);
+  return true;
+}

launcher/commands/jellyfin-command.ts

@@ -0,0 +1,71 @@
+import { fail } from '../log.js';
+import { runAppCommandWithInherit } from '../mpv.js';
+import { commandExists } from '../util.js';
+import { runJellyfinPlayMenu } from '../jellyfin.js';
+import type { LauncherCommandContext } from './context.js';
+
+export async function runJellyfinCommand(context: LauncherCommandContext): Promise<boolean> {
+  const { args, appPath, scriptPath, mpvSocketPath, launcherJellyfinConfig } = context;
+  if (!appPath) {
+    return false;
+  }
+
+  if (args.jellyfin) {
+    const forwarded = ['--jellyfin'];
+    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
+    runAppCommandWithInherit(appPath, forwarded);
+  }
+
+  if (args.jellyfinLogin) {
+    const serverUrl = args.jellyfinServer || launcherJellyfinConfig.serverUrl || '';
+    const username = args.jellyfinUsername || launcherJellyfinConfig.username || '';
+    const password = args.jellyfinPassword || '';
+    if (!serverUrl || !username || !password) {
+      fail(
+        '--jellyfin-login requires server, username, and password. Pass flags or run `subminer --jellyfin`.',
+      );
+    }
+    const forwarded = [
+      '--jellyfin-login',
+      '--jellyfin-server',
+      serverUrl,
+      '--jellyfin-username',
+      username,
+      '--jellyfin-password',
+      password,
+    ];
+    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
+    runAppCommandWithInherit(appPath, forwarded);
+  }
+
+  if (args.jellyfinLogout) {
+    const forwarded = ['--jellyfin-logout'];
+    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
+    runAppCommandWithInherit(appPath, forwarded);
+  }
+
+  if (args.jellyfinPlay) {
+    if (!args.useRofi && !commandExists('fzf')) {
+      fail('fzf not found. Install fzf or use -R for rofi.');
+    }
+    if (args.useRofi && !commandExists('rofi')) {
+      fail('rofi not found. Install rofi or omit -R for fzf.');
+    }
+    await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
+    return true;
+  }
+
+  if (args.jellyfinDiscovery) {
+    const forwarded = ['--start'];
+    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
+    runAppCommandWithInherit(appPath, forwarded);
+  }
+
+  return Boolean(
+    args.jellyfin ||
+    args.jellyfinLogin ||
+    args.jellyfinLogout ||
+    args.jellyfinPlay ||
+    args.jellyfinDiscovery,
+  );
+}

launcher/commands/mpv-command.ts

@@ -0,0 +1,62 @@
+import { fail, log } from '../log.js';
+import { waitForUnixSocketReady, launchMpvIdleDetached } from '../mpv.js';
+import type { LauncherCommandContext } from './context.js';
+
+interface MpvCommandDeps {
+  waitForUnixSocketReady(socketPath: string, timeoutMs: number): Promise<boolean>;
+  launchMpvIdleDetached(
+    socketPath: string,
+    appPath: string,
+    args: LauncherCommandContext['args'],
+  ): Promise<void>;
+}
+
+const defaultDeps: MpvCommandDeps = {
+  waitForUnixSocketReady,
+  launchMpvIdleDetached,
+};
+
+export async function runMpvPreAppCommand(
+  context: LauncherCommandContext,
+  deps: MpvCommandDeps = defaultDeps,
+): Promise<boolean> {
+  const { args, mpvSocketPath, processAdapter } = context;
+  if (args.mpvSocket) {
+    processAdapter.writeStdout(`${mpvSocketPath}\n`);
+    return true;
+  }
+
+  if (!args.mpvStatus) {
+    return false;
+  }
+
+  const ready = await deps.waitForUnixSocketReady(mpvSocketPath, 500);
+  log(
+    ready ? 'info' : 'warn',
+    args.logLevel,
+    `[mpv] socket ${ready ? 'ready' : 'not ready'}: ${mpvSocketPath}`,
+  );
+  processAdapter.exit(ready ? 0 : 1);
+  return true;
+}
+
+export async function runMpvPostAppCommand(
+  context: LauncherCommandContext,
+  deps: MpvCommandDeps = defaultDeps,
+): Promise<boolean> {
+  const { args, appPath, mpvSocketPath } = context;
+  if (!args.mpvIdle) {
+    return false;
+  }
+  if (!appPath) {
+    fail('SubMiner app binary not found. Install to ~/.local/bin/ or set SUBMINER_APPIMAGE_PATH.');
+  }
+
+  await deps.launchMpvIdleDetached(mpvSocketPath, appPath, args);
+  const ready = await deps.waitForUnixSocketReady(mpvSocketPath, 8000);
+  if (!ready) {
+    fail(`MPV IPC socket not ready after idle launch: ${mpvSocketPath}`);
+  }
+  log('info', args.logLevel, `[mpv] idle instance ready on ${mpvSocketPath}`);
+  return true;
+}

launcher/commands/playback-command.ts

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail, log } from '../log.js';
+import { commandExists, isYoutubeTarget, realpathMaybe, resolvePathMaybe } from '../util.js';
+import { collectVideos, showFzfMenu, showRofiMenu } from '../picker.js';
+import {
+  loadSubtitleIntoMpv,
+  startMpv,
+  startOverlay,
+  state,
+  stopOverlay,
+  waitForUnixSocketReady,
+} from '../mpv.js';
+import { generateYoutubeSubtitles } from '../youtube.js';
+import type { Args } from '../types.js';
+import type { LauncherCommandContext } from './context.js';
+
+function checkDependencies(args: Args): void {
+  const missing: string[] = [];
+
+  if (!commandExists('mpv')) missing.push('mpv');
+
+  if (args.targetKind === 'url' && isYoutubeTarget(args.target) && !commandExists('yt-dlp')) {
+    missing.push('yt-dlp');
+  }
+
+  if (
+    args.targetKind === 'url' &&
+    isYoutubeTarget(args.target) &&
+    args.youtubeSubgenMode !== 'off' &&
+    !commandExists('ffmpeg')
+  ) {
+    missing.push('ffmpeg');
+  }
+
+  if (missing.length > 0) fail(`Missing dependencies: ${missing.join(' ')}`);
+}
+
+function checkPickerDependencies(args: Args): void {
+  if (args.useRofi) {
+    if (!commandExists('rofi')) fail('Missing dependency: rofi');
+    return;
+  }
+
+  if (!commandExists('fzf')) fail('Missing dependency: fzf');
+}
+
+async function chooseTarget(
+  args: Args,
+  scriptPath: string,
+): Promise<{ target: string; kind: 'file' | 'url' } | null> {
+  if (args.target) {
+    return { target: args.target, kind: args.targetKind as 'file' | 'url' };
+  }
+
+  const searchDir = realpathMaybe(resolvePathMaybe(args.directory));
+  if (!fs.existsSync(searchDir) || !fs.statSync(searchDir).isDirectory()) {
+    fail(`Directory not found: ${searchDir}`);
+  }
+
+  const videos = collectVideos(searchDir, args.recursive);
+  if (videos.length === 0) {
+    fail(`No video files found in: ${searchDir}`);
+  }
+
+  log('info', args.logLevel, `Browsing: ${searchDir} (${videos.length} videos found)`);
+
+  const selected = args.useRofi
+    ? showRofiMenu(videos, searchDir, args.recursive, scriptPath, args.logLevel)
+    : showFzfMenu(videos);
+
+  if (!selected) return null;
+  return { target: selected, kind: 'file' };
+}
+
+function registerCleanup(context: LauncherCommandContext): void {
+  const { args, processAdapter } = context;
+  processAdapter.onSignal('SIGINT', () => {
+    stopOverlay(args);
+    processAdapter.exit(130);
+  });
+  processAdapter.onSignal('SIGTERM', () => {
+    stopOverlay(args);
+    processAdapter.exit(143);
+  });
+}
+
+export async function runPlaybackCommand(context: LauncherCommandContext): Promise<void> {
+  const { args, appPath, scriptPath, mpvSocketPath, processAdapter } = context;
+  if (!appPath) {
+    fail('SubMiner AppImage not found. Install to ~/.local/bin/ or set SUBMINER_APPIMAGE_PATH.');
+  }
+
+  if (!args.target) {
+    checkPickerDependencies(args);
+  }
+
+  const targetChoice = await chooseTarget(args, scriptPath);
+  if (!targetChoice) {
+    log('info', args.logLevel, 'No video selected, exiting');
+    processAdapter.exit(0);
+  }
+
+  checkDependencies({
+    ...args,
+    target: targetChoice ? targetChoice.target : args.target,
+    targetKind: targetChoice ? targetChoice.kind : 'url',
+  });
+
+  registerCleanup(context);
+
+  const selectedTarget = targetChoice
+    ? {
+        target: targetChoice.target,
+        kind: targetChoice.kind as 'file' | 'url',
+      }
+    : { target: args.target, kind: 'url' as const };
+
+  const isYoutubeUrl = selectedTarget.kind === 'url' && isYoutubeTarget(selectedTarget.target);
+  let preloadedSubtitles: { primaryPath?: string; secondaryPath?: string } | undefined;
+
+  if (isYoutubeUrl && args.youtubeSubgenMode === 'preprocess') {
+    log('info', args.logLevel, 'YouTube subtitle mode: preprocess');
+    const generated = await generateYoutubeSubtitles(selectedTarget.target, args);
+    preloadedSubtitles = {
+      primaryPath: generated.primaryPath,
+      secondaryPath: generated.secondaryPath,
+    };
+    log(
+      'info',
+      args.logLevel,
+      `YouTube preprocess result: primary=${generated.primaryPath ? 'ready' : 'missing'}, secondary=${generated.secondaryPath ? 'ready' : 'missing'}`,
+    );
+  } else if (isYoutubeUrl && args.youtubeSubgenMode === 'automatic') {
+    log('info', args.logLevel, 'YouTube subtitle mode: automatic (background)');
+  } else if (isYoutubeUrl) {
+    log('info', args.logLevel, 'YouTube subtitle mode: off');
+  }
+
+  startMpv(
+    selectedTarget.target,
+    selectedTarget.kind,
+    args,
+    mpvSocketPath,
+    appPath,
+    preloadedSubtitles,
+  );
+
+  if (isYoutubeUrl && args.youtubeSubgenMode === 'automatic') {
+    void generateYoutubeSubtitles(selectedTarget.target, args, async (lang, subtitlePath) => {
+      try {
+        await loadSubtitleIntoMpv(mpvSocketPath, subtitlePath, lang === 'primary', args.logLevel);
+      } catch (error) {
+        log(
+          'warn',
+          args.logLevel,
+          `Generated subtitle ready but failed to load in mpv: ${(error as Error).message}`,
+        );
+      }
+    }).catch((error) => {
+      log(
+        'warn',
+        args.logLevel,
+        `Background subtitle generation failed: ${(error as Error).message}`,
+      );
+    });
+  }
+
+  const ready = await waitForUnixSocketReady(mpvSocketPath, 10000);
+  const shouldStartOverlay = args.startOverlay || args.autoStartOverlay;
+  if (shouldStartOverlay) {
+    if (ready) {
+      log('info', args.logLevel, 'MPV IPC socket ready, starting SubMiner overlay');
+    } else {
+      log(
+        'info',
+        args.logLevel,
+        'MPV IPC socket not ready after timeout, starting SubMiner overlay anyway',
+      );
+    }
+    await startOverlay(appPath, args, mpvSocketPath);
+  } else if (ready) {
+    log(
+      'info',
+      args.logLevel,
+      'MPV IPC socket ready, overlay auto-start disabled (use y-s to start)',
+    );
+  } else {
+    log(
+      'info',
+      args.logLevel,
+      'MPV IPC socket not ready yet, overlay auto-start disabled (use y-s to start)',
+    );
+  }
+
+  await new Promise<void>((resolve) => {
+    if (!state.mpvProc) {
+      stopOverlay(args);
+      resolve();
+      return;
+    }
+    state.mpvProc.on('exit', (code) => {
+      stopOverlay(args);
+      processAdapter.setExitCode(code ?? 0);
+      resolve();
+    });
+  });
+}

launcher/config-path.ts

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { resolveConfigFilePath } from '../src/config/path-resolution.js';
+
+export function resolveMainConfigPath(): string {
+  return resolveConfigFilePath({
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    homeDir: os.homedir(),
+    existsSync: fs.existsSync,
+  });
+}

launcher/main.ts

@@ -1,404 +1,98 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
-import { resolveConfigFilePath } from '../src/config/path-resolution.js';
-import type { Args } from './types.js';
-import { log, fail } from './log.js';
-import { commandExists, isYoutubeTarget, resolvePathMaybe, realpathMaybe } from './util.js';
 import {
-  parseArgs,
-  loadLauncherYoutubeSubgenConfig,
   loadLauncherJellyfinConfig,
+  loadLauncherYoutubeSubgenConfig,
+  parseArgs,
   readPluginRuntimeConfig,
 } from './config.js';
-import { showRofiMenu, showFzfMenu, collectVideos } from './picker.js';
-import {
-  state,
-  startMpv,
-  startOverlay,
-  stopOverlay,
-  launchTexthookerOnly,
-  findAppBinary,
-  loadSubtitleIntoMpv,
-  runAppCommandWithInherit,
-  launchMpvIdleDetached,
-  waitForUnixSocketReady,
-} from './mpv.js';
-import { generateYoutubeSubtitles } from './youtube.js';
-import { runJellyfinPlayMenu } from './jellyfin.js';
+import { fail, log } from './log.js';
+import { findAppBinary, state } from './mpv.js';
+import { nodeProcessAdapter } from './process-adapter.js';
+import type { LauncherCommandContext } from './commands/context.js';
+import { runDoctorCommand } from './commands/doctor-command.js';
+import { runConfigCommand } from './commands/config-command.js';
+import { runMpvPostAppCommand, runMpvPreAppCommand } from './commands/mpv-command.js';
+import { runAppPassthroughCommand, runTexthookerCommand } from './commands/app-command.js';
+import { runJellyfinCommand } from './commands/jellyfin-command.js';
+import { runPlaybackCommand } from './commands/playback-command.js';
 
-function checkDependencies(args: Args): void {
-  const missing: string[] = [];
-
-  if (!commandExists('mpv')) missing.push('mpv');
-
-  if (args.targetKind === 'url' && isYoutubeTarget(args.target) && !commandExists('yt-dlp')) {
-    missing.push('yt-dlp');
-  }
-
-  if (
-    args.targetKind === 'url' &&
-    isYoutubeTarget(args.target) &&
-    args.youtubeSubgenMode !== 'off' &&
-    !commandExists('ffmpeg')
-  ) {
-    missing.push('ffmpeg');
-  }
-
-  if (missing.length > 0) fail(`Missing dependencies: ${missing.join(' ')}`);
-}
-
-function checkPickerDependencies(args: Args): void {
-  if (args.useRofi) {
-    if (!commandExists('rofi')) fail('Missing dependency: rofi');
-    return;
-  }
-
-  if (!commandExists('fzf')) fail('Missing dependency: fzf');
-}
-
-async function chooseTarget(
-  args: Args,
+function createCommandContext(
+  args: ReturnType<typeof parseArgs>,
   scriptPath: string,
-): Promise<{ target: string; kind: 'file' | 'url' } | null> {
-  if (args.target) {
-    return { target: args.target, kind: args.targetKind as 'file' | 'url' };
-  }
-
-  const searchDir = realpathMaybe(resolvePathMaybe(args.directory));
-  if (!fs.existsSync(searchDir) || !fs.statSync(searchDir).isDirectory()) {
-    fail(`Directory not found: ${searchDir}`);
-  }
-
-  const videos = collectVideos(searchDir, args.recursive);
-  if (videos.length === 0) {
-    fail(`No video files found in: ${searchDir}`);
-  }
-
-  log('info', args.logLevel, `Browsing: ${searchDir} (${videos.length} videos found)`);
-
-  const selected = args.useRofi
-    ? showRofiMenu(videos, searchDir, args.recursive, scriptPath, args.logLevel)
-    : showFzfMenu(videos);
-
-  if (!selected) return null;
-  return { target: selected, kind: 'file' };
+  mpvSocketPath: string,
+  appPath: string | null,
+): LauncherCommandContext {
+  return {
+    args,
+    scriptPath,
+    scriptName: path.basename(scriptPath),
+    mpvSocketPath,
+    appPath,
+    launcherJellyfinConfig: loadLauncherJellyfinConfig(),
+    processAdapter: nodeProcessAdapter,
+  };
 }
 
-function registerCleanup(args: Args): void {
-  process.on('SIGINT', () => {
-    stopOverlay(args);
-    process.exit(130);
-  });
-  process.on('SIGTERM', () => {
-    stopOverlay(args);
-    process.exit(143);
-  });
-}
-
-function resolveMainConfigPath(): string {
-  return resolveConfigFilePath({
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir: os.homedir(),
-    existsSync: fs.existsSync,
-  });
-}
-
-function runDoctor(args: Args, appPath: string | null, mpvSocketPath: string): never {
-  const checks: Array<{ label: string; ok: boolean; detail: string }> = [
-    {
-      label: 'app binary',
-      ok: Boolean(appPath),
-      detail: appPath || 'not found (set SUBMINER_APPIMAGE_PATH)',
-    },
-    {
-      label: 'mpv',
-      ok: commandExists('mpv'),
-      detail: commandExists('mpv') ? 'found' : 'missing',
-    },
-    {
-      label: 'yt-dlp',
-      ok: commandExists('yt-dlp'),
-      detail: commandExists('yt-dlp') ? 'found' : 'missing (optional unless YouTube URLs)',
-    },
-    {
-      label: 'ffmpeg',
-      ok: commandExists('ffmpeg'),
-      detail: commandExists('ffmpeg') ? 'found' : 'missing (optional unless subtitle generation)',
-    },
-    {
-      label: 'fzf',
-      ok: commandExists('fzf'),
-      detail: commandExists('fzf') ? 'found' : 'missing (optional if using rofi)',
-    },
-    {
-      label: 'rofi',
-      ok: commandExists('rofi'),
-      detail: commandExists('rofi') ? 'found' : 'missing (optional if using fzf)',
-    },
-    {
-      label: 'config',
-      ok: fs.existsSync(resolveMainConfigPath()),
-      detail: resolveMainConfigPath(),
-    },
-    {
-      label: 'mpv socket path',
-      ok: true,
-      detail: mpvSocketPath,
-    },
-  ];
-
-  const hasHardFailure = checks.some((entry) =>
-    entry.label === 'app binary' || entry.label === 'mpv' ? !entry.ok : false,
-  );
-
-  for (const check of checks) {
-    log(check.ok ? 'info' : 'warn', args.logLevel, `[doctor] ${check.label}: ${check.detail}`);
+function ensureAppPath(context: LauncherCommandContext): string {
+  if (context.appPath) {
+    return context.appPath;
   }
-  process.exit(hasHardFailure ? 1 : 0);
+  if (context.processAdapter.platform() === 'darwin') {
+    fail(
+      'SubMiner app binary not found. Install SubMiner.app to /Applications or ~/Applications, or set SUBMINER_APPIMAGE_PATH.',
+    );
+  }
+  fail('SubMiner AppImage not found. Install to ~/.local/bin/ or set SUBMINER_APPIMAGE_PATH.');
 }
 
 async function main(): Promise<void> {
   const scriptPath = process.argv[1] || 'subminer';
   const scriptName = path.basename(scriptPath);
   const launcherConfig = loadLauncherYoutubeSubgenConfig();
-  const launcherJellyfinConfig = loadLauncherJellyfinConfig();
   const args = parseArgs(process.argv.slice(2), scriptName, launcherConfig);
   const pluginRuntimeConfig = readPluginRuntimeConfig(args.logLevel);
-  const mpvSocketPath = pluginRuntimeConfig.socketPath;
+  const appPath = findAppBinary(scriptPath);
 
   log('debug', args.logLevel, `Wrapper log level set to: ${args.logLevel}`);
 
-  const appPath = findAppBinary(process.argv[1] || 'subminer');
-  if (args.doctor) {
-    runDoctor(args, appPath, mpvSocketPath);
-  }
+  const context = createCommandContext(args, scriptPath, pluginRuntimeConfig.socketPath, appPath);
 
-  if (args.configPath) {
-    process.stdout.write(`${resolveMainConfigPath()}\n`);
+  if (runDoctorCommand(context)) {
     return;
   }
 
-  if (args.configShow) {
-    const configPath = resolveMainConfigPath();
-    if (!fs.existsSync(configPath)) {
-      fail(`Config file not found: ${configPath}`);
-    }
-    const contents = fs.readFileSync(configPath, 'utf8');
-    process.stdout.write(contents);
-    if (!contents.endsWith('\n')) {
-      process.stdout.write('\n');
-    }
+  if (runConfigCommand(context)) {
     return;
   }
 
-  if (args.mpvSocket) {
-    process.stdout.write(`${mpvSocketPath}\n`);
+  if (await runMpvPreAppCommand(context)) {
     return;
   }
 
-  if (args.mpvStatus) {
-    const ready = await waitForUnixSocketReady(mpvSocketPath, 500);
-    log(
-      ready ? 'info' : 'warn',
-      args.logLevel,
-      `[mpv] socket ${ready ? 'ready' : 'not ready'}: ${mpvSocketPath}`,
-    );
-    process.exit(ready ? 0 : 1);
-  }
+  const resolvedAppPath = ensureAppPath(context);
+  state.appPath = resolvedAppPath;
+  const appContext: LauncherCommandContext = {
+    ...context,
+    appPath: resolvedAppPath,
+  };
 
-  if (!appPath) {
-    if (process.platform === 'darwin') {
-      fail(
-        'SubMiner app binary not found. Install SubMiner.app to /Applications or ~/Applications, or set SUBMINER_APPIMAGE_PATH.',
-      );
-    }
-    fail('SubMiner AppImage not found. Install to ~/.local/bin/ or set SUBMINER_APPIMAGE_PATH.');
-  }
-  state.appPath = appPath;
-
-  if (args.appPassthrough) {
-    runAppCommandWithInherit(appPath, args.appArgs);
-  }
-
-  if (args.mpvIdle) {
-    await launchMpvIdleDetached(mpvSocketPath, appPath, args);
-    const ready = await waitForUnixSocketReady(mpvSocketPath, 8000);
-    if (!ready) {
-      fail(`MPV IPC socket not ready after idle launch: ${mpvSocketPath}`);
-    }
-    log('info', args.logLevel, `[mpv] idle instance ready on ${mpvSocketPath}`);
+  if (runAppPassthroughCommand(appContext)) {
     return;
   }
 
-  if (args.texthookerOnly) {
-    launchTexthookerOnly(appPath, args);
+  if (await runMpvPostAppCommand(appContext)) {
+    return;
   }
 
-  if (args.jellyfin) {
-    const forwarded = ['--jellyfin'];
-    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
-    runAppCommandWithInherit(appPath, forwarded);
+  if (runTexthookerCommand(appContext)) {
+    return;
   }
 
-  if (args.jellyfinLogin) {
-    const serverUrl = args.jellyfinServer || launcherJellyfinConfig.serverUrl || '';
-    const username = args.jellyfinUsername || launcherJellyfinConfig.username || '';
-    const password = args.jellyfinPassword || '';
-    if (!serverUrl || !username || !password) {
-      fail(
-        '--jellyfin-login requires server, username, and password. Pass flags or run `subminer --jellyfin`.',
-      );
-    }
-    const forwarded = [
-      '--jellyfin-login',
-      '--jellyfin-server',
-      serverUrl,
-      '--jellyfin-username',
-      username,
-      '--jellyfin-password',
-      password,
-    ];
-    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
-    runAppCommandWithInherit(appPath, forwarded);
+  if (await runJellyfinCommand(appContext)) {
+    return;
   }
 
-  if (args.jellyfinLogout) {
-    const forwarded = ['--jellyfin-logout'];
-    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
-    runAppCommandWithInherit(appPath, forwarded);
-  }
-
-  if (args.jellyfinPlay) {
-    if (!args.useRofi && !commandExists('fzf')) {
-      fail('fzf not found. Install fzf or use -R for rofi.');
-    }
-    if (args.useRofi && !commandExists('rofi')) {
-      fail('rofi not found. Install rofi or omit -R for fzf.');
-    }
-    await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
-  }
-
-  if (args.jellyfinDiscovery) {
-    const forwarded = ['--start'];
-    if (args.logLevel !== 'info') forwarded.push('--log-level', args.logLevel);
-    runAppCommandWithInherit(appPath, forwarded);
-  }
-
-  if (!args.target) {
-    checkPickerDependencies(args);
-  }
-
-  const targetChoice = await chooseTarget(args, process.argv[1] || 'subminer');
-  if (!targetChoice) {
-    log('info', args.logLevel, 'No video selected, exiting');
-    process.exit(0);
-  }
-
-  checkDependencies({
-    ...args,
-    target: targetChoice ? targetChoice.target : args.target,
-    targetKind: targetChoice ? targetChoice.kind : 'url',
-  });
-
-  registerCleanup(args);
-
-  let selectedTarget = targetChoice
-    ? {
-        target: targetChoice.target,
-        kind: targetChoice.kind as 'file' | 'url',
-      }
-    : { target: args.target, kind: 'url' as const };
-
-  const isYoutubeUrl = selectedTarget.kind === 'url' && isYoutubeTarget(selectedTarget.target);
-  let preloadedSubtitles: { primaryPath?: string; secondaryPath?: string } | undefined;
-
-  if (isYoutubeUrl && args.youtubeSubgenMode === 'preprocess') {
-    log('info', args.logLevel, 'YouTube subtitle mode: preprocess');
-    const generated = await generateYoutubeSubtitles(selectedTarget.target, args);
-    preloadedSubtitles = {
-      primaryPath: generated.primaryPath,
-      secondaryPath: generated.secondaryPath,
-    };
-    log(
-      'info',
-      args.logLevel,
-      `YouTube preprocess result: primary=${generated.primaryPath ? 'ready' : 'missing'}, secondary=${generated.secondaryPath ? 'ready' : 'missing'}`,
-    );
-  } else if (isYoutubeUrl && args.youtubeSubgenMode === 'automatic') {
-    log('info', args.logLevel, 'YouTube subtitle mode: automatic (background)');
-  } else if (isYoutubeUrl) {
-    log('info', args.logLevel, 'YouTube subtitle mode: off');
-  }
-
-  startMpv(
-    selectedTarget.target,
-    selectedTarget.kind,
-    args,
-    mpvSocketPath,
-    appPath,
-    preloadedSubtitles,
-  );
-
-  if (isYoutubeUrl && args.youtubeSubgenMode === 'automatic') {
-    void generateYoutubeSubtitles(selectedTarget.target, args, async (lang, subtitlePath) => {
-      try {
-        await loadSubtitleIntoMpv(mpvSocketPath, subtitlePath, lang === 'primary', args.logLevel);
-      } catch (error) {
-        log(
-          'warn',
-          args.logLevel,
-          `Generated subtitle ready but failed to load in mpv: ${(error as Error).message}`,
-        );
-      }
-    }).catch((error) => {
-      log(
-        'warn',
-        args.logLevel,
-        `Background subtitle generation failed: ${(error as Error).message}`,
-      );
-    });
-  }
-
-  const ready = await waitForUnixSocketReady(mpvSocketPath, 10000);
-  const shouldStartOverlay = args.startOverlay || args.autoStartOverlay;
-  if (shouldStartOverlay) {
-    if (ready) {
-      log('info', args.logLevel, 'MPV IPC socket ready, starting SubMiner overlay');
-    } else {
-      log(
-        'info',
-        args.logLevel,
-        'MPV IPC socket not ready after timeout, starting SubMiner overlay anyway',
-      );
-    }
-    await startOverlay(appPath, args, mpvSocketPath);
-  } else if (ready) {
-    log(
-      'info',
-      args.logLevel,
-      'MPV IPC socket ready, overlay auto-start disabled (use y-s to start)',
-    );
-  } else {
-    log(
-      'info',
-      args.logLevel,
-      'MPV IPC socket not ready yet, overlay auto-start disabled (use y-s to start)',
-    );
-  }
-
-  await new Promise<void>((resolve) => {
-    if (!state.mpvProc) {
-      stopOverlay(args);
-      resolve();
-      return;
-    }
-    state.mpvProc.on('exit', (code) => {
-      stopOverlay(args);
-      process.exitCode = code ?? 0;
-      resolve();
-    });
-  });
+  await runPlaybackCommand(appContext);
 }
 
 main().catch((error: unknown) => {

launcher/process-adapter.ts

@@ -0,0 +1,21 @@
+export interface ProcessAdapter {
+  platform(): NodeJS.Platform;
+  onSignal(signal: NodeJS.Signals, handler: () => void): void;
+  writeStdout(text: string): void;
+  exit(code: number): never;
+  setExitCode(code: number): void;
+}
+
+export const nodeProcessAdapter: ProcessAdapter = {
+  platform: () => process.platform,
+  onSignal: (signal, handler) => {
+    process.on(signal, handler);
+  },
+  writeStdout: (text) => {
+    process.stdout.write(text);
+  },
+  exit: (code) => process.exit(code),
+  setExitCode: (code) => {
+    process.exitCode = code;
+  },
+};