@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/packages/tools/docs-to-voice/index.ts

@@ -4,32 +4,13 @@ import path from 'node:path';
 import https from 'node:https';
 import http from 'node:http';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { SystemError, UserInputError, createToolRunner } from '@laitszkin/tool-utils';
 
 const DEFAULT_API_ENDPOINT =
   'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation';
 const DEFAULT_API_MODEL = 'qwen3-tts';
 const DEFAULT_API_VOICE = 'Cherry';
 
-interface DocsToVoiceArgs {
-  inputText: string | null;
-  inputFile: string | null;
-  projectDir: string;
-  projectName: string | null;
-  outputName: string | null;
-  mode: string;
-  voice: string | null;
-  rate: string | null;
-  speechRate: string | null;
-  apiEndpoint: string;
-  apiModel: string;
-  apiVoice: string;
-  apiKey: string | null;
-  maxChars: string | null;
-  noAutoProsody: boolean;
-  force: boolean;
-  help: boolean;
-}
-
 interface TimelineEntry {
   index: number;
   text: string;
@@ -39,113 +20,15 @@ interface TimelineEntry {
   endMs: number;
 }
 
-function parseArgs(args: string[]): DocsToVoiceArgs {
-  const parsed: DocsToVoiceArgs = {
-    inputText: null,
-    inputFile: null,
-    projectDir: '.',
-    projectName: null,
-    outputName: null,
-    mode: 'say',
-    voice: null,
-    rate: null,
-    speechRate: null,
-    apiEndpoint: DEFAULT_API_ENDPOINT,
-    apiModel: DEFAULT_API_MODEL,
-    apiVoice: DEFAULT_API_VOICE,
-    apiKey: null,
-    maxChars: null,
-    noAutoProsody: false,
-    force: false,
-    help: false,
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--help' || arg === '-h') {
-      parsed.help = true;
-      continue;
-    }
-    if (arg.startsWith('--')) {
-      const eqIndex = arg.indexOf('=');
-      let key: string;
-      let value: string;
-
-      if (eqIndex !== -1) {
-        key = arg.slice(2, eqIndex);
-        value = arg.slice(eqIndex + 1);
-      } else {
-        key = arg.slice(2);
-        value = args[++i] || '';
-      }
-
-      switch (key) {
-        case 'text':
-          parsed.inputText = value;
-          break;
-        case 'input':
-        case 'input-file':
-          parsed.inputFile = value;
-          break;
-        case 'project-dir':
-          parsed.projectDir = value;
-          break;
-        case 'project-name':
-          parsed.projectName = value;
-          break;
-        case 'output-name':
-          parsed.outputName = value;
-          break;
-        case 'engine':
-        case 'mode':
-          parsed.mode = value.toLowerCase();
-          break;
-        case 'voice':
-          parsed.voice = value;
-          break;
-        case 'rate':
-          parsed.rate = value;
-          break;
-        case 'speech-rate':
-          parsed.speechRate = value;
-          break;
-        case 'api-endpoint':
-          parsed.apiEndpoint = value;
-          break;
-        case 'api-model':
-          parsed.apiModel = value;
-          break;
-        case 'api-voice':
-          parsed.apiVoice = value;
-          break;
-        case 'api-key':
-          parsed.apiKey = value;
-          break;
-        case 'max-chars':
-          parsed.maxChars = value;
-          break;
-        case 'no-auto-prosody':
-          parsed.noAutoProsody = true;
-          break;
-        case 'force':
-          parsed.force = true;
-          break;
-      }
-    }
-  }
-
-  return parsed;
-}
-
-function readInputText(opts: DocsToVoiceArgs): string {
-  if (opts.inputFile) {
-    const inputPath = path.resolve(opts.inputFile);
+function readInputText(inputFile: string | null, inputText: string | null): string {
+  if (inputFile) {
+    const inputPath = path.resolve(inputFile);
     if (!fs.existsSync(inputPath)) {
-      throw new Error(`Input file not found: ${inputPath}`);
+      throw new UserInputError(`Input file not found: ${inputPath}`);
     }
     return fs.readFileSync(inputPath, 'utf-8');
   }
-  return opts.inputText || '';
+  return inputText || '';
 }
 
 function splitSentences(rawText: string): string[] {
@@ -349,8 +232,10 @@ function applySpeechRateToAudio(outputPath: string, speechRate: number): void {
     }
   } catch (err: unknown) {
     if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
-    throw new Error(
+    throw new SystemError(
       `ffmpeg failed while applying --speech-rate: ${err instanceof Error ? err.message : 'unknown error'}`,
+      undefined,
+      { cause: err },
     );
   }
 }
@@ -400,7 +285,7 @@ function splitTextForTts(text: string, maxChars: number | null): string[] {
 
 function concatAudioFiles(partPaths: string[], outputPath: string): void {
   if (partPaths.length === 0) {
-    throw new Error('No chunk audio generated for concatenation.');
+    throw new SystemError('No chunk audio generated for concatenation.');
   }
   if (partPaths.length === 1) {
     fs.copyFileSync(partPaths[0], outputPath);
@@ -419,8 +304,10 @@ function concatAudioFiles(partPaths: string[], outputPath: string): void {
       { stdio: 'ignore', timeout: 120000 },
     );
   } catch (err: unknown) {
-    throw new Error(
+    throw new SystemError(
       `ffmpeg concat failed: ${err instanceof Error ? err.message : 'unknown error'}`,
+      undefined,
+      { cause: err },
     );
   } finally {
     try { fs.unlinkSync(listFile); fs.rmdirSync(path.dirname(listFile)); } catch { /* ignore */ }
@@ -484,323 +371,316 @@ function requestAlibabaCloudTTS(
           const audioFormat = audio.format || audio.mime_type || '';
 
           if (!audioUrl && !audioData) {
-            reject(new Error('API response does not contain output.audio.url or output.audio.data'));
+            reject(new SystemError('API response does not contain output.audio.url or output.audio.data'));
             return;
           }
 
           resolve({ audioUrl, audioData, audioFormat });
         } catch {
-          reject(new Error('API response is not valid JSON.'));
+          reject(new SystemError('API response is not valid JSON.'));
         }
       });
       res.on('error', reject);
     });
 
     req.on('error', reject);
-    req.on('timeout', () => { req.destroy(); reject(new Error('API request timed out')); });
+    req.on('timeout', () => { req.destroy(); reject(new SystemError('API request timed out')); });
     req.write(payload);
     req.end();
   });
 }
 
-export async function docsToVoiceHandler(args: string[], context: ToolContext): Promise<number> {
-  const stdout = context.stdout || process.stdout;
-  const stderr = context.stderr || process.stderr;
-
-  try {
-    const opts = parseArgs(args);
-
-    if (opts.help) {
-      stdout.write(`Usage: apltk docs-to-voice [options]
-
-Convert text into audio and sentence timelines.
-
-Options:
-  --input, --input-file <path>  Path to input text file
-  --text <string>               Raw text input
-  --project-dir <path>          Root project directory (default: .)
-  --project-name <name>         Folder name under DIR/audio/
-  --output-name <name>          Output filename
-  --engine, --mode <mode>       TTS mode: say (default) | api
-  --voice <name>                macOS say voice
-  --rate <wpm>                  macOS say rate
-  --speech-rate <factor>        Speech rate multiplier (e.g. 1.2)
-  --api-endpoint <url>          Alibaba Cloud TTS endpoint
-  --api-model <name>            Alibaba Cloud model (default: qwen3-tts)
-  --api-voice <name>            Alibaba Cloud voice (default: Cherry)
-  --api-key <key>               Alibaba Cloud API key
-  --max-chars <n>               Max chars per TTS chunk (0 disables)
-  --no-auto-prosody             Disable punctuation pause enhancement
-  --force                       Overwrite existing files
-`);
-      return 0;
-    }
-
-    if (opts.mode !== 'say' && opts.mode !== 'api') {
-      stderr.write('Error: --mode must be one of: say, api\n');
-      return 1;
-    }
-
-    const sourceText = readInputText(opts);
-    if (!sourceText.trim()) {
-      stderr.write('Error: No text content found for conversion.\n');
-      return 1;
-    }
-
-    // Resolve output directory
-    const projectDir = path.resolve(opts.projectDir);
-    const projectName = opts.projectName || path.basename(projectDir);
-    if (!projectName) {
-      stderr.write('Error: Unable to determine project name.\n');
-      return 1;
-    }
-
-    const outputDir = path.join(projectDir, 'audio', projectName);
-    fs.mkdirSync(outputDir, { recursive: true });
-
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const outputName = opts.outputName || `voice-${timestamp}`;
-    const hasExtension = outputName.includes('.');
-
-    if (opts.mode === 'say') {
-      // macOS say mode
-      const textChunks = splitTextForTts(sourceText, opts.maxChars ? parseInt(opts.maxChars, 10) || null : null);
-      if (textChunks.length === 0) {
-        stderr.write('Error: No text content found for conversion.\n');
-        return 1;
+const schema = {
+  options: {
+    'text': { type: 'string' as const },
+    'input': { type: 'string' as const },
+    'input-file': { type: 'string' as const },
+    'project-dir': { type: 'string' as const, default: '.' },
+    'project-name': { type: 'string' as const },
+    'output-name': { type: 'string' as const },
+    'engine': { type: 'string' as const },
+    'mode': { type: 'string' as const, default: 'say' },
+    'voice': { type: 'string' as const },
+    'rate': { type: 'string' as const },
+    'speech-rate': { type: 'string' as const },
+    'api-endpoint': { type: 'string' as const, default: DEFAULT_API_ENDPOINT },
+    'api-model': { type: 'string' as const, default: DEFAULT_API_MODEL },
+    'api-voice': { type: 'string' as const, default: DEFAULT_API_VOICE },
+    'api-key': { type: 'string' as const },
+    'max-chars': { type: 'string' as const },
+    'no-auto-prosody': { type: 'boolean' as const, default: false },
+    'force': { type: 'boolean' as const, default: false },
+  },
+  allowPositionals: true,
+  usage: 'apltk docs-to-voice [options]',
+  description: 'Convert text into audio and sentence timelines.',
+  handler: async (
+    values: Record<string, unknown>,
+    _positionals: string[],
+    context: ToolContext,
+  ): Promise<number> => {
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+
+      // Resolve args (previously handled by parseCliArgs)
+      const inputText: string | null = (values['text'] as string | undefined) ?? null;
+      const inputFile: string | null = (values['input'] as string | undefined) || (values['input-file'] as string | undefined) || null;
+      const projectDir: string = (values['project-dir'] as string) || '.';
+      const projectName: string | null = (values['project-name'] as string | undefined) ?? null;
+      const outputName: string | null = (values['output-name'] as string | undefined) ?? null;
+      const mode: string = ((values['mode'] as string | undefined) || (values['engine'] as string | undefined) || 'say').toLowerCase();
+      const voice: string | null = (values['voice'] as string | undefined) ?? null;
+      const rate: string | null = (values['rate'] as string | undefined) ?? null;
+      const speechRate: string | null = (values['speech-rate'] as string | undefined) ?? null;
+      const apiEndpoint: string = (values['api-endpoint'] as string) || DEFAULT_API_ENDPOINT;
+      const apiModel: string = (values['api-model'] as string) || DEFAULT_API_MODEL;
+      const apiVoice: string = (values['api-voice'] as string) || DEFAULT_API_VOICE;
+      const apiKey: string | null = (values['api-key'] as string | undefined) ?? null;
+      const maxChars: string | null = (values['max-chars'] as string | undefined) ?? null;
+      const noAutoProsody: boolean = !!values['no-auto-prosody'];
+      const force: boolean = !!values['force'];
+
+      if (mode !== 'say' && mode !== 'api') {
+        throw new UserInputError('--mode must be one of: say, api');
       }
 
-      // Check if `say` is available
-      try {
-        execSync('which say', { stdio: 'ignore' });
-      } catch {
-        stderr.write("Error: macOS 'say' command not found.\n");
-        return 1;
+      const sourceText = readInputText(inputFile, inputText);
+      if (!sourceText.trim()) {
+        throw new UserInputError('No text content found for conversion.');
       }
 
-      const finalOutputName = hasExtension ? outputName : `${outputName}.aiff`;
-      const outputPath = path.join(outputDir, finalOutputName);
-
-      if (fs.existsSync(outputPath) && !opts.force) {
-        stderr.write(`Error: Output already exists: ${outputPath}. Use --force to overwrite.\n`);
-        return 1;
+      // Resolve output directory
+      const resolvedProjectDir = path.resolve(projectDir);
+      const resolvedProjectName = projectName || path.basename(resolvedProjectDir);
+      if (!resolvedProjectName) {
+        throw new UserInputError('Unable to determine project name.');
       }
 
-      // Build prosody-enhanced text
-      const chunks = opts.noAutoProsody ? textChunks : textChunks.map(buildAutoProsodyText);
+      const outputDir = path.join(resolvedProjectDir, 'audio', resolvedProjectName);
+      fs.mkdirSync(outputDir, { recursive: true });
 
-      if (chunks.length === 1) {
-        // Single say command
-        const sayArgs = ['-o', outputPath];
-        if (opts.voice) sayArgs.push('-v', opts.voice);
-        if (opts.rate) sayArgs.push('-r', opts.rate);
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      const outName = outputName || `voice-${timestamp}`;
+      const hasExtension = outName.includes('.');
 
-        const tmpFile = path.join(fs.mkdtempSync('docs-to-voice-'), 'input.txt');
-        fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
-        fs.writeFileSync(tmpFile, chunks[0], 'utf-8');
-        sayArgs.push('-f', tmpFile);
+      if (mode === 'say') {
+        const finalOutputName = hasExtension ? outName : `${outName}.aiff`;
+        const outputPath = path.join(outputDir, finalOutputName);
 
-        try {
-          execSync(`say ${sayArgs.map((a) => (a.includes(' ') ? `"${a}"` : a)).join(' ')}`, {
-            stdio: 'ignore',
-            timeout: 300000,
-          });
-        } catch (err: unknown) {
-          const msg = err instanceof Error ? err.message : 'unknown error';
-          throw new Error(`say mode failed: ${msg}`);
-        } finally {
-          try { fs.unlinkSync(tmpFile); fs.rmdirSync(path.dirname(tmpFile)); } catch { /* ignore */ }
+        if (fs.existsSync(outputPath) && !force) {
+          throw new UserInputError(`Output already exists: ${outputPath}. Use --force to overwrite.`);
         }
-      } else {
-        // Multiple chunks: generate then concat
-        const tempDir = fs.mkdtempSync('docs-to-voice-say-');
-        const partPaths: string[] = [];
-        const partExt = path.extname(outputPath) || '.aiff';
 
-        try {
-          for (let i = 0; i < chunks.length; i++) {
-            const partPath = path.join(tempDir, `part-${String(i + 1).padStart(4, '0')}${partExt}`);
-            const sayArgs = ['-o', partPath];
-            if (opts.voice) sayArgs.push('-v', opts.voice);
-            if (opts.rate) sayArgs.push('-r', opts.rate);
-
-            const tmpFile = path.join(tempDir, `chunk-${i}.txt`);
-            fs.writeFileSync(tmpFile, chunks[i], 'utf-8');
-            sayArgs.push('-f', tmpFile);
-
-            execSync(
-              `say ${sayArgs.map((a) => (a.includes(' ') ? `"${a}"` : a)).join(' ')}`,
-              { stdio: 'ignore', timeout: 300000 },
-            );
-            partPaths.push(partPath);
+        // Build prosody-enhanced text
+        const textChunks = splitTextForTts(sourceText, maxChars ? parseInt(maxChars, 10) || null : null);
+        if (textChunks.length === 0) {
+          throw new UserInputError('No text content found for conversion.');
+        }
+        const chunks = noAutoProsody ? textChunks : textChunks.map(buildAutoProsodyText);
+
+        if (chunks.length === 1) {
+          // Single say command
+          const sayArgs = ['-o', outputPath];
+          if (voice) sayArgs.push('-v', voice);
+          if (rate) sayArgs.push('-r', rate);
+
+          const tmpFile = path.join(fs.mkdtempSync('docs-to-voice-'), 'input.txt');
+          fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
+          fs.writeFileSync(tmpFile, chunks[0], 'utf-8');
+          sayArgs.push('-f', tmpFile);
+
+          try {
+            execSync(`say ${sayArgs.map((a) => (a.includes(' ') ? `"${a}"` : a)).join(' ')}`, {
+              stdio: 'ignore',
+              timeout: 300000,
+            });
+          } catch (err: unknown) {
+            const msg = err instanceof Error ? err.message : 'unknown error';
+            throw new SystemError(`say mode failed: ${msg}`);
+          } finally {
+            try { fs.unlinkSync(tmpFile); fs.rmdirSync(path.dirname(tmpFile)); } catch { /* ignore */ }
           }
+        } else {
+          // Multiple chunks: generate then concat
+          const tempDir = fs.mkdtempSync('docs-to-voice-say-');
+          const partPaths: string[] = [];
+          const partExt = path.extname(outputPath) || '.aiff';
+
+          try {
+            for (let i = 0; i < chunks.length; i++) {
+              const partPath = path.join(tempDir, `part-${String(i + 1).padStart(4, '0')}${partExt}`);
+              const sArgs = ['-o', partPath];
+              if (voice) sArgs.push('-v', voice);
+              if (rate) sArgs.push('-r', rate);
+
+              const tFile = path.join(tempDir, `chunk-${i}.txt`);
+              fs.writeFileSync(tFile, chunks[i], 'utf-8');
+              sArgs.push('-f', tFile);
+
+              execSync(
+                `say ${sArgs.map((a) => (a.includes(' ') ? `"${a}"` : a)).join(' ')}`,
+                { stdio: 'ignore', timeout: 300000 },
+              );
+              partPaths.push(partPath);
+            }
 
-          concatAudioFiles(partPaths, outputPath);
-        } finally {
-          try { fs.rmSync(tempDir, { recursive: true }); } catch { /* ignore */ }
+            concatAudioFiles(partPaths, outputPath);
+          } finally {
+            try { fs.rmSync(tempDir, { recursive: true }); } catch { /* ignore */ }
+          }
         }
-      }
 
-      // Apply speech rate if requested
-      if (opts.speechRate) {
-        const rate = parseFloat(opts.speechRate);
-        if (rate > 0) applySpeechRateToAudio(outputPath, rate);
-      }
+        // Apply speech rate if requested
+        if (speechRate) {
+          const rateVal = parseFloat(speechRate);
+          if (rateVal > 0) applySpeechRateToAudio(outputPath, rateVal);
+        }
 
-      // Write timeline files
-      writeTimelineFiles(sourceText, outputPath, null);
-      stdout.write(`${outputPath}\n`);
-    } else {
-      // API mode
-      const apiKey = opts.apiKey;
-      if (!apiKey) {
-        stderr.write('Error: --api-key is required for api mode.\n');
-        return 1;
-      }
+        // Write timeline files
+        writeTimelineFiles(sourceText, outputPath, null);
+        stdout.write(`${outputPath}\n`);
+      } else {
+        // API mode
+        if (!apiKey) {
+          throw new UserInputError('--api-key is required for api mode.');
+        }
 
-      const sentences = splitSentences(sourceText);
-      if (sentences.length === 0) {
-        stderr.write('Error: No text content found for conversion.\n');
-        return 1;
-      }
+        const sentences = splitSentences(sourceText);
+        if (sentences.length === 0) {
+          throw new UserInputError('No text content found for conversion.');
+        }
 
-      const maxChars = opts.maxChars ? parseInt(opts.maxChars, 10) || null : null;
+        const maxCharsNum = maxChars ? parseInt(maxChars, 10) || null : null;
 
-      // Build request items from sentences
-      interface RequestItem {
-        sentenceIndex: number;
-        text: string;
-      }
-      const requestItems: RequestItem[] = [];
-      for (let si = 0; si < sentences.length; si++) {
-        const sentence = sentences[si];
-        if (maxChars && sentence.length > maxChars) {
-          for (let i = 0; i < sentence.length; i += maxChars) {
-            requestItems.push({ sentenceIndex: si, text: sentence.slice(i, i + maxChars) });
+        // Build request items from sentences
+        interface RequestItem {
+          sentenceIndex: number;
+          text: string;
+        }
+        const requestItems: RequestItem[] = [];
+        for (let si = 0; si < sentences.length; si++) {
+          const sentence = sentences[si];
+          if (maxCharsNum && sentence.length > maxCharsNum) {
+            for (let i = 0; i < sentence.length; i += maxCharsNum) {
+              requestItems.push({ sentenceIndex: si, text: sentence.slice(i, i + maxCharsNum) });
+            }
+          } else {
+            requestItems.push({ sentenceIndex: si, text: sentence });
           }
-        } else {
-          requestItems.push({ sentenceIndex: si, text: sentence });
         }
-      }
 
-      if (requestItems.length === 0) {
-        stderr.write('Error: No text content found for conversion.\n');
-        return 1;
-      }
+        if (requestItems.length === 0) {
+          throw new UserInputError('No text content found for conversion.');
+        }
 
-      const tempDir = fs.mkdtempSync('docs-to-voice-api-');
-      const partPaths: string[] = [];
-      let partExt = '';
-      const sentenceDurations = new Array(sentences.length).fill(0);
-      const sentenceDurationKnown = new Array(sentences.length).fill(true);
-
-      try {
-        for (let i = 0; i < requestItems.length; i++) {
-          const item = requestItems[i];
-          const apiResult = await requestAlibabaCloudTTS(
-            opts.apiEndpoint,
-            apiKey,
-            opts.apiModel,
-            opts.apiVoice,
-            item.text,
-          );
-
-          const currentExt = apiResult.audioFormat || 'wav';
-          if (!partExt) partExt = currentExt;
-
-          const partPath = path.join(tempDir, `part-${String(i + 1).padStart(4, '0')}.${currentExt}`);
-          if (apiResult.audioUrl) {
-            await downloadBinary(apiResult.audioUrl, partPath);
-          } else if (apiResult.audioData) {
-            fs.writeFileSync(partPath, Buffer.from(apiResult.audioData, 'base64'));
-          } else {
-            throw new Error('No audio data in API response.');
-          }
+        const tempDir = fs.mkdtempSync('docs-to-voice-api-');
+        const partPaths: string[] = [];
+        let partExt = '';
+        const sentenceDurations = new Array(sentences.length).fill(0);
+        const sentenceDurationKnown = new Array(sentences.length).fill(true);
+
+        try {
+          for (let i = 0; i < requestItems.length; i++) {
+            const item = requestItems[i];
+            const apiResult = await requestAlibabaCloudTTS(
+              apiEndpoint,
+              apiKey,
+              apiModel,
+              apiVoice,
+              item.text,
+            );
+
+            const currentExt = apiResult.audioFormat || 'wav';
+            if (!partExt) partExt = currentExt;
+
+            const partPath = path.join(tempDir, `part-${String(i + 1).padStart(4, '0')}.${currentExt}`);
+            if (apiResult.audioUrl) {
+              await downloadBinary(apiResult.audioUrl, partPath);
+            } else if (apiResult.audioData) {
+              fs.writeFileSync(partPath, Buffer.from(apiResult.audioData, 'base64'));
+            } else {
+              throw new SystemError('No audio data in API response.');
+            }
+
+            if (!fs.existsSync(partPath) || fs.statSync(partPath).size === 0) {
+              throw new SystemError(`Failed to generate audio chunk ${i + 1}.`);
+            }
+            partPaths.push(partPath);
 
-          if (!fs.existsSync(partPath) || fs.statSync(partPath).size === 0) {
-            throw new Error(`Failed to generate audio chunk ${i + 1}.`);
+            const partDuration = readDurationSeconds(partPath);
+            if (partDuration === null || partDuration <= 0) {
+              sentenceDurationKnown[item.sentenceIndex] = false;
+            } else {
+              sentenceDurations[item.sentenceIndex] += partDuration;
+            }
           }
-          partPaths.push(partPath);
 
-          const partDuration = readDurationSeconds(partPath);
-          if (partDuration === null || partDuration <= 0) {
-            sentenceDurationKnown[item.sentenceIndex] = false;
-          } else {
-            sentenceDurations[item.sentenceIndex] += partDuration;
+          const finalOutputName = hasExtension
+            ? outName
+            : `${outName}.${partExt || 'wav'}`;
+          const outputPath = path.join(outputDir, finalOutputName);
+
+          if (fs.existsSync(outputPath) && !force) {
+            throw new UserInputError(`Output already exists: ${outputPath}. Use --force to overwrite.`);
           }
-        }
 
-        const finalOutputName = hasExtension
-          ? outputName
-          : `${outputName}.${partExt || 'wav'}`;
-        const outputPath = path.join(outputDir, finalOutputName);
+          concatAudioFiles(partPaths, outputPath);
 
-        if (fs.existsSync(outputPath) && !opts.force) {
-          stderr.write(`Error: Output already exists: ${outputPath}. Use --force to overwrite.\n`);
-          return 1;
-        }
+          // Build timeline durations
+          let timelineDurations: number[] | null = null;
+          const unknownIndexes = sentenceDurationKnown
+            .map((known, idx) => (known ? -1 : idx))
+            .filter((idx) => idx >= 0);
+
+          if (unknownIndexes.length === 0 && sentenceDurations.reduce((a, b) => a + b, 0) > 0) {
+            timelineDurations = sentenceDurations;
+          } else if (unknownIndexes.length > 0) {
+            const outputDuration = readDurationSeconds(outputPath);
+            const knownTotal = sentenceDurations.reduce(
+              (sum, val, idx) => (sentenceDurationKnown[idx] ? sum + val : sum),
+              0,
+            );
 
-        concatAudioFiles(partPaths, outputPath);
-
-        // Build timeline durations
-        let timelineDurations: number[] | null = null;
-        const unknownIndexes = sentenceDurationKnown
-          .map((known, idx) => (known ? -1 : idx))
-          .filter((idx) => idx >= 0);
-
-        if (unknownIndexes.length === 0 && sentenceDurations.reduce((a, b) => a + b, 0) > 0) {
-          timelineDurations = sentenceDurations;
-        } else if (unknownIndexes.length > 0) {
-          const outputDuration = readDurationSeconds(outputPath);
-          const knownTotal = sentenceDurations.reduce(
-            (sum, val, idx) => (sentenceDurationKnown[idx] ? sum + val : sum),
-            0,
-          );
-
-          if (outputDuration && outputDuration > knownTotal) {
-            const remaining = outputDuration - knownTotal;
-            const unknownWeights = unknownIndexes.map((idx) => sentenceWeight(sentences[idx]));
-            const totalUnknownWeight = unknownWeights.reduce((a, b) => a + b, 0);
-
-            if (totalUnknownWeight > 0) {
-              for (let wi = 0; wi < unknownIndexes.length; wi++) {
-                sentenceDurations[unknownIndexes[wi]] +=
-                  remaining * (unknownWeights[wi] / totalUnknownWeight);
+            if (outputDuration && outputDuration > knownTotal) {
+              const remaining = outputDuration - knownTotal;
+              const unknownWeights = unknownIndexes.map((idx) => sentenceWeight(sentences[idx]));
+              const totalUnknownWeight = unknownWeights.reduce((a, b) => a + b, 0);
+
+              if (totalUnknownWeight > 0) {
+                for (let wi = 0; wi < unknownIndexes.length; wi++) {
+                  sentenceDurations[unknownIndexes[wi]] +=
+                    remaining * (unknownWeights[wi] / totalUnknownWeight);
+                }
+                timelineDurations = sentenceDurations;
               }
-              timelineDurations = sentenceDurations;
             }
           }
-        }
 
-        // Apply speech rate if requested
-        if (opts.speechRate) {
-          const rate = parseFloat(opts.speechRate);
-          if (rate > 0) {
-            applySpeechRateToAudio(outputPath, rate);
-            if (timelineDurations) {
-              timelineDurations = timelineDurations.map((d) => d / rate);
+          // Apply speech rate if requested
+          if (speechRate) {
+            const rateVal = parseFloat(speechRate);
+            if (rateVal > 0) {
+              applySpeechRateToAudio(outputPath, rateVal);
+              if (timelineDurations) {
+                timelineDurations = timelineDurations.map((d) => d / rateVal);
+              }
             }
           }
-        }
 
-        writeTimelineFiles(sourceText, outputPath, timelineDurations);
-        stdout.write(`${outputPath}\n`);
-      } finally {
-        try { fs.rmSync(tempDir, { recursive: true }); } catch { /* ignore */ }
+          writeTimelineFiles(sourceText, outputPath, timelineDurations);
+          stdout.write(`${outputPath}\n`);
+        } finally {
+          try { fs.rmSync(tempDir, { recursive: true }); } catch { /* ignore */ }
+        }
       }
-    }
 
-    return 0;
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : 'Unknown error';
-    stderr.write(`Error: ${msg}\n`);
-    return 1;
-  }
-}
+      return 0;
+  },
+};
 
 export const tool: ToolDefinition = {
   name: 'docs-to-voice',
   category: 'media',
   description: 'Convert text into audio and sentence timelines.',
-  handler: docsToVoiceHandler,
+  handler: createToolRunner(schema),
 };