@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/packages/tools/render-katex/index.ts

@@ -2,6 +2,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { createToolRunner, UserInputError, SystemError } from '@laitszkin/tool-utils';
 
 interface KatexArgs {
   tex: string | null;
@@ -28,138 +29,46 @@ interface KatexArgs {
   minRuleThickness: number | null;
 }
 
-function parseArgs(args: string[]): KatexArgs {
-  const parsed: KatexArgs = {
-    tex: null,
-    inputFile: null,
-    outputFormat: 'html-fragment',
-    katexFormat: 'htmlAndMathml',
-    displayMode: false,
-    leqno: false,
-    fleqn: false,
-    colorIsTextColor: false,
-    noThrowOnError: false,
-    outputFile: null,
-    cssHref: 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css',
-    title: 'KaTeX Render',
-    lang: 'en',
+function convertValuesToKatexArgs(values: Record<string, unknown>): KatexArgs {
+  const rawOutputFormat = values['output-format'] as string | undefined;
+  const rawKatexFormat = values['katex-format'] as string | undefined;
+  const rawMaxSize = values['max-size'] as string | undefined;
+  const rawMaxExpand = values['max-expand'] as string | undefined;
+  const rawMinRuleThickness = values['min-rule-thickness'] as string | undefined;
+
+  return {
+    tex: (values['tex'] as string | undefined) ?? null,
+    inputFile: (values['input-file'] as string | undefined) ?? null,
+    outputFormat: rawOutputFormat && ['html-fragment', 'html-page', 'markdown-inline', 'markdown-block', 'json'].includes(rawOutputFormat)
+      ? rawOutputFormat : 'html-fragment',
+    katexFormat: rawKatexFormat && ['html', 'mathml', 'htmlAndMathml'].includes(rawKatexFormat)
+      ? rawKatexFormat : 'htmlAndMathml',
+    displayMode: !!values['display-mode'],
+    leqno: !!values['leqno'],
+    fleqn: !!values['fleqn'],
+    colorIsTextColor: !!values['color-is-text-color'],
+    noThrowOnError: !!values['no-throw-on-error'],
+    outputFile: (values['output-file'] as string | undefined) ?? null,
+    cssHref: (values['css-href'] as string) || 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css',
+    title: (values['title'] as string) || 'KaTeX Render',
+    lang: (values['lang'] as string) || 'en',
     help: false,
-    macro: [],
-    macroFile: null,
-    errorColor: null,
-    strict: null,
-    trust: null,
-    maxSize: null,
-    maxExpand: null,
-    minRuleThickness: null,
+    macro: values['macro'] ? [values['macro'] as string] : [],
+    macroFile: (values['macro-file'] as string | undefined) ?? null,
+    errorColor: (values['error-color'] as string | undefined) ?? null,
+    strict: (values['strict'] as string | undefined) ?? null,
+    trust: (values['trust'] as string | undefined) ?? null,
+    maxSize: rawMaxSize ? Number(rawMaxSize) : null,
+    maxExpand: rawMaxExpand ? Number(rawMaxExpand) : null,
+    minRuleThickness: rawMinRuleThickness ? Number(rawMinRuleThickness) : null,
   };
-
-  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 | boolean | null;
-
-      if (eqIndex !== -1) {
-        key = arg.slice(2, eqIndex);
-        value = arg.slice(eqIndex + 1);
-      } else {
-        key = arg.slice(2);
-        const next = args[i + 1];
-        if (next !== undefined && !next.startsWith('--')) {
-          value = next;
-          i++;
-        } else {
-          value = true;
-        }
-      }
-
-      switch (key) {
-        case 'tex':
-          parsed.tex = String(value);
-          break;
-        case 'input-file':
-          parsed.inputFile = String(value);
-          break;
-        case 'output-format':
-          if (['html-fragment', 'html-page', 'markdown-inline', 'markdown-block', 'json'].includes(String(value))) {
-            parsed.outputFormat = String(value);
-          }
-          break;
-        case 'katex-format':
-          if (['html', 'mathml', 'htmlAndMathml'].includes(String(value))) {
-            parsed.katexFormat = String(value);
-          }
-          break;
-        case 'display-mode':
-          parsed.displayMode = value === true || value === 'true';
-          break;
-        case 'leqno':
-          parsed.leqno = value === true || value === 'true';
-          break;
-        case 'fleqn':
-          parsed.fleqn = value === true || value === 'true';
-          break;
-        case 'color-is-text-color':
-          parsed.colorIsTextColor = value === true || value === 'true';
-          break;
-        case 'no-throw-on-error':
-          parsed.noThrowOnError = value === true || value === 'true';
-          break;
-        case 'output-file':
-          parsed.outputFile = String(value);
-          break;
-        case 'css-href':
-          parsed.cssHref = String(value);
-          break;
-        case 'title':
-          parsed.title = String(value);
-          break;
-        case 'lang':
-          parsed.lang = String(value);
-          break;
-        case 'macro':
-          parsed.macro.push(String(value));
-          break;
-        case 'macro-file':
-          parsed.macroFile = String(value);
-          break;
-        case 'error-color':
-          parsed.errorColor = String(value);
-          break;
-        case 'strict':
-          parsed.strict = String(value);
-          break;
-        case 'trust':
-          parsed.trust = String(value);
-          break;
-        case 'max-size':
-          parsed.maxSize = Number(value);
-          break;
-        case 'max-expand':
-          parsed.maxExpand = Number(value);
-          break;
-        case 'min-rule-thickness':
-          parsed.minRuleThickness = Number(value);
-          break;
-      }
-    }
-  }
-
-  return parsed;
 }
 
 function loadTex(opts: KatexArgs): string {
   if (opts.inputFile) {
     const inputPath = path.resolve(opts.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').trim();
   }
@@ -208,7 +117,7 @@ function wrapOutput(renderedHtml: string, tex: string, opts: KatexArgs): string
         2,
       ) + '\n';
     default:
-      throw new Error(`Unsupported output format: ${opts.outputFormat}`);
+      throw new UserInputError(`Unsupported output format: ${opts.outputFormat}`);
   }
 }
 
@@ -223,110 +132,117 @@ function writeOutput(content: string, outputFile: string | null, stdout: NodeJS.
   stdout.write(`${outputPath}\n`);
 }
 
-export async function renderKatexHandler(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 render-katex [options]
-
-Render TeX with KaTeX and emit insertion-ready output.
-
-Options:
-  --tex <string>              Raw TeX expression without delimiters
-  --input-file <path>         Path to a text file containing raw TeX
-  --output-format <format>    html-fragment (default) | html-page | markdown-inline | markdown-block | json
-  --katex-format <format>     html | mathml | htmlAndMathml (default)
-  --display-mode              Render in display mode
-  --output-file <path>        Write output to a file
-  --css-href <url>            Stylesheet href (default: KaTeX CDN)
-  --title <text>              Document title for html-page
-  --lang <code>               HTML lang attribute (default: en)
-`);
-      return 0;
-    }
-
-    const tex = loadTex(opts);
-    if (!tex) {
-      stderr.write('Error: Input TeX is empty.\n');
-      return 1;
-    }
-
-    // Build npx katex command
-    const cmdArgs: string[] = [
-      'npx',
-      '--yes',
-      '--package',
-      'katex',
-      'katex',
-      '--format',
-      opts.katexFormat,
-    ];
-
-    if (opts.displayMode) cmdArgs.push('--display-mode');
-    if (opts.leqno === true) cmdArgs.push('--leqno');
-    if (opts.fleqn === true) cmdArgs.push('--fleqn');
-    if (opts.colorIsTextColor === true) cmdArgs.push('--color-is-text-color');
-    if (opts.noThrowOnError === true) cmdArgs.push('--no-throw-on-error');
-
-    if (opts.errorColor) cmdArgs.push('--error-color', opts.errorColor);
-    if (opts.strict) cmdArgs.push('--strict', opts.strict);
-    if (opts.trust) cmdArgs.push('--trust', opts.trust);
-    if (opts.maxSize !== null) cmdArgs.push('--max-size', String(opts.maxSize));
-    if (opts.maxExpand !== null) cmdArgs.push('--max-expand', String(opts.maxExpand));
-    if (opts.minRuleThickness !== null) cmdArgs.push('--min-rule-thickness', String(opts.minRuleThickness));
-    // Handle macro args
-    for (const macro of opts.macro) {
-      cmdArgs.push('--macro', macro);
-    }
-    if (opts.macroFile) cmdArgs.push('--macro-file', opts.macroFile);
-
-    // Write tex to temp file and pass it to katex
-    const tmpFile = path.join(
-      fs.mkdtempSync('katex-'),
-      'input.tex',
-    );
-    fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
-    fs.writeFileSync(tmpFile, tex + '\n', 'utf-8');
-    cmdArgs.push('--input', tmpFile);
+// ── Schema ────────────────────────────────────────────────────────────────────
+
+const schema = {
+  options: {
+    'tex': { type: 'string' as const },
+    'input-file': { type: 'string' as const },
+    'output-format': { type: 'string' as const, default: 'html-fragment' },
+    'katex-format': { type: 'string' as const, default: 'htmlAndMathml' },
+    'display-mode': { type: 'boolean' as const },
+    'leqno': { type: 'boolean' as const },
+    'fleqn': { type: 'boolean' as const },
+    'color-is-text-color': { type: 'boolean' as const },
+    'no-throw-on-error': { type: 'boolean' as const },
+    'output-file': { type: 'string' as const },
+    'css-href': { type: 'string' as const, default: 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css' },
+    'title': { type: 'string' as const, default: 'KaTeX Render' },
+    'lang': { type: 'string' as const, default: 'en' },
+    'macro': { type: 'string' as const },
+    'macro-file': { type: 'string' as const },
+    'error-color': { type: 'string' as const },
+    'strict': { type: 'string' as const },
+    'trust': { type: 'string' as const },
+    'max-size': { type: 'string' as const },
+    'max-expand': { type: 'string' as const },
+    'min-rule-thickness': { type: 'string' as const },
+  },
+  allowPositionals: true,
+  usage: 'apltk render-katex [options]',
+  description: 'Render TeX with KaTeX and emit insertion-ready output.',
+  handler: async (
+    values: Record<string, unknown>,
+    positionals: string[],
+    context: ToolContext,
+  ): Promise<number> => {
+    const stdout = context.stdout || process.stdout;
+    const stderr = context.stderr || process.stderr;
+
+      const opts = convertValuesToKatexArgs(values);
+
+      const tex = loadTex(opts);
+      if (!tex) {
+        throw new UserInputError('Input TeX is empty.');
+      }
 
-    let renderedHtml: string;
-    try {
-      const result = execSync(cmdArgs.join(' '), {
-        encoding: 'utf-8',
-        maxBuffer: 10 * 1024 * 1024,
-        timeout: 60000,
-      });
-      renderedHtml = result.trim();
-    } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : 'KaTeX CLI failed.';
-      stderr.write(`Error: ${message}\n`);
-      return 1;
-    } finally {
+      // Build npx katex command
+      const cmdArgs: string[] = [
+        'npx',
+        '--yes',
+        '--package',
+        'katex',
+        'katex',
+        '--format',
+        opts.katexFormat,
+      ];
+
+      if (opts.displayMode) cmdArgs.push('--display-mode');
+      if (opts.leqno === true) cmdArgs.push('--leqno');
+      if (opts.fleqn === true) cmdArgs.push('--fleqn');
+      if (opts.colorIsTextColor === true) cmdArgs.push('--color-is-text-color');
+      if (opts.noThrowOnError === true) cmdArgs.push('--no-throw-on-error');
+
+      if (opts.errorColor) cmdArgs.push('--error-color', opts.errorColor);
+      if (opts.strict) cmdArgs.push('--strict', opts.strict);
+      if (opts.trust) cmdArgs.push('--trust', opts.trust);
+      if (opts.maxSize !== null) cmdArgs.push('--max-size', String(opts.maxSize));
+      if (opts.maxExpand !== null) cmdArgs.push('--max-expand', String(opts.maxExpand));
+      if (opts.minRuleThickness !== null) cmdArgs.push('--min-rule-thickness', String(opts.minRuleThickness));
+      // Handle macro args
+      for (const macro of opts.macro) {
+        cmdArgs.push('--macro', macro);
+      }
+      if (opts.macroFile) cmdArgs.push('--macro-file', opts.macroFile);
+
+      // Write tex to temp file and pass it to katex
+      const tmpFile = path.join(
+        fs.mkdtempSync('katex-'),
+        'input.tex',
+      );
+      fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
+      fs.writeFileSync(tmpFile, tex + '\n', 'utf-8');
+      cmdArgs.push('--input', tmpFile);
+
+      let renderedHtml: string;
       try {
-        fs.unlinkSync(tmpFile);
-        fs.rmdirSync(path.dirname(tmpFile));
-      } catch {
-        // ignore cleanup errors
+        const result = execSync(cmdArgs.join(' '), {
+          encoding: 'utf-8',
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 60000,
+        });
+        renderedHtml = result.trim();
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : 'KaTeX CLI failed.';
+        throw new SystemError(message);
+      } finally {
+        try {
+          fs.unlinkSync(tmpFile);
+          fs.rmdirSync(path.dirname(tmpFile));
+        } catch {
+          // ignore cleanup errors
+        }
       }
-    }
 
-    const wrapped = wrapOutput(renderedHtml, tex, opts);
-    writeOutput(wrapped, opts.outputFile, stdout);
-    return 0;
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error';
-    stderr.write(`Error: ${message}\n`);
-    return 1;
-  }
-}
+      const wrapped = wrapOutput(renderedHtml, tex, opts);
+      writeOutput(wrapped, opts.outputFile, stdout);
+      return 0;
+  },
+};
 
 export const tool: ToolDefinition = {
   name: 'render-katex',
   category: 'media',
   description: 'Render TeX with KaTeX and emit insertion-ready output.',
-  handler: renderKatexHandler,
+  handler: createToolRunner(schema),
 };

package/packages/tools/render-katex/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-render-katex",
-  "version": "4.0.8",
-  "description": "Apollo Toolkit — CLI tool",
+  "version": "5.0.0",
+  "description": "Apollo Toolkit \u2014 CLI tool",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,4 +19,4 @@
   "dependencies": {
     "@laitszkin/tool-registry": "*"
   }
-}
+}

package/packages/tools/review-threads/dist/index.d.ts

@@ -1,3 +1,15 @@
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+/**
+ * reviewThreadsHandler — Known carryover from createToolRunner migration.
+ *
+ * Reason for not using createToolRunner:
+ * - Positional subcommand architecture (list/resolve) doesn't map cleanly
+ *   to createToolRunner's options schema.
+ * - Error handling follows the AppError convention (UserInputError/SystemError
+ *   throws) — errors propagate to the CLI boundary's formatAppError.
+ * - Argument parsing is handled manually via a 63-line parseArgs().
+ *
+ * See DESIGN.md §2.3 for the full architecture discussion.
+ */
 export declare function reviewThreadsHandler(argv: string[], context: ToolContext): Promise<number>;
 export declare const tool: ToolDefinition;