@laitszkin/apollo-toolkit 4.1.4 → 5.0.0

package/packages/tools/enforce-video-aspect-ratio/index.ts

@@ -2,112 +2,23 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
-
-interface AspectArgs {
-  inputVideo: string | null;
-  outputVideo: string | null;
-  inPlace: boolean;
-  targetSize: string | null;
-  targetWidth: number | null;
-  targetHeight: number | null;
-  aspect: string | null;
-  force: boolean;
-  ffmpegBin: string;
-  ffprobeBin: string;
-  help: boolean;
-}
-
-function parseArgs(args: string[]): AspectArgs {
-  const parsed: AspectArgs = {
-    inputVideo: null,
-    outputVideo: null,
-    inPlace: false,
-    targetSize: null,
-    targetWidth: null,
-    targetHeight: null,
-    aspect: null,
-    force: false,
-    ffmpegBin: 'ffmpeg',
-    ffprobeBin: 'ffprobe',
-    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 'input':
-        case 'input-video':
-          parsed.inputVideo = value;
-          break;
-        case 'output':
-        case 'output-video':
-          parsed.outputVideo = value;
-          break;
-        case 'in-place':
-          parsed.inPlace = true;
-          break;
-        case 'aspect':
-          parsed.aspect = value;
-          break;
-        case 'target-size':
-          parsed.targetSize = value;
-          break;
-        case 'target-width':
-          parsed.targetWidth = parseInt(value, 10) || null;
-          break;
-        case 'target-height':
-          parsed.targetHeight = parseInt(value, 10) || null;
-          break;
-        case 'force':
-          parsed.force = true;
-          break;
-        case 'ffmpeg-bin':
-          parsed.ffmpegBin = value;
-          break;
-        case 'ffprobe-bin':
-          parsed.ffprobeBin = value;
-          break;
-      }
-    } else if (!parsed.inputVideo && !arg.startsWith('-')) {
-      parsed.inputVideo = arg;
-    }
-  }
-
-  return parsed;
-}
+import { SystemError, UserInputError, createToolRunner } from '@laitszkin/tool-utils';
 
 function parseSize(value: string): { width: number; height: number } {
   const match = value.trim().toLowerCase().match(/^(\d{2,5})x(\d{2,5})$/);
-  if (!match) throw new Error('Invalid size format. Use WIDTHxHEIGHT, for example 1080x1920.');
+  if (!match) throw new UserInputError('Invalid size format. Use WIDTHxHEIGHT, for example 1080x1920.');
   const width = parseInt(match[1], 10);
   const height = parseInt(match[2], 10);
-  if (width <= 0 || height <= 0) throw new Error('Width and height must be positive integers.');
+  if (width <= 0 || height <= 0) throw new UserInputError('Width and height must be positive integers.');
   return { width, height };
 }
 
 function parseRatio(value: string): { width: number; height: number } {
   const match = value.trim().match(/^(\d+):(\d+)$/);
-  if (!match) throw new Error('Invalid aspect ratio format. Use WIDTH:HEIGHT, for example 16:9.');
+  if (!match) throw new UserInputError('Invalid aspect ratio format. Use WIDTH:HEIGHT, for example 16:9.');
   const width = parseInt(match[1], 10);
   const height = parseInt(match[2], 10);
-  if (width <= 0 || height <= 0) throw new Error('Aspect ratio values must be positive integers.');
+  if (width <= 0 || height <= 0) throw new UserInputError('Aspect ratio values must be positive integers.');
   return { width, height };
 }
 
@@ -120,14 +31,14 @@ function probeVideoSize(videoPath: string, ffprobeBin: string): { width: number;
   const payload = JSON.parse(result);
   const streams = payload.streams;
   if (!Array.isArray(streams) || streams.length === 0) {
-    throw new Error(`No video stream found in ${videoPath}.`);
+    throw new SystemError(`No video stream found in ${videoPath}.`);
   }
 
   const first = streams[0];
   const width = first.width;
   const height = first.height;
   if (typeof width !== 'number' || typeof height !== 'number' || width <= 0 || height <= 0) {
-    throw new Error(`Invalid video dimensions from ffprobe for ${videoPath}.`);
+    throw new SystemError(`Invalid video dimensions from ffprobe for ${videoPath}.`);
   }
   return { width, height };
 }
@@ -174,87 +85,97 @@ function buildVideoFilter(
   };
 }
 
-function resolveTargetSize(opts: AspectArgs): { width: number; height: number } {
-  if (opts.aspect) {
-    // Aspect ratio mode: derive target size from input
-    // We'll resolve this later in the handler
-    return { width: 0, height: 0 };
-  }
-
-  if (opts.targetSize && (opts.targetWidth !== null || opts.targetHeight !== null)) {
-    throw new Error('Use either --target-size or --target-width/--target-height, not both.');
+function resolveTargetSize(
+  targetSize: string | null,
+  targetWidth: number | null,
+  targetHeight: number | null,
+): { width: number; height: number } {
+  if (targetSize && (targetWidth !== null || targetHeight !== null)) {
+    throw new UserInputError('Use either --target-size or --target-width/--target-height, not both.');
   }
 
-  if (opts.targetSize) return parseSize(opts.targetSize);
+  if (targetSize) return parseSize(targetSize);
 
-  const width = opts.targetWidth || parseInt(process.env.TEXT_TO_SHORT_VIDEO_WIDTH || '1080', 10);
-  const height = opts.targetHeight || parseInt(process.env.TEXT_TO_SHORT_VIDEO_HEIGHT || '1920', 10);
+  const width = targetWidth || parseInt(process.env.TEXT_TO_SHORT_VIDEO_WIDTH || '1080', 10);
+  const height = targetHeight || parseInt(process.env.TEXT_TO_SHORT_VIDEO_HEIGHT || '1920', 10);
 
-  if (width <= 0 || height <= 0) throw new Error('Target width and height must be positive integers.');
+  if (width <= 0 || height <= 0) throw new UserInputError('Target width and height must be positive integers.');
   return { width, height };
 }
 
-export async function enforceVideoAspectRatioHandler(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 enforce-video-aspect-ratio [options]
-
-Resize video output to a target aspect ratio or size.
-
-Options:
-  --input, --input-video <path>   Path to input video (required)
-  --output, --output-video <path> Path to output video
-  --in-place                      Overwrite input file
-  --aspect <ratio>                Target aspect ratio, e.g. 9:16 or 16:9
-  --target-size <size>            Target size, e.g. 1080x1920
-  --target-width <px>             Target width
-  --target-height <px>            Target height
-  --force                         Overwrite existing output
-  --ffmpeg-bin <path>             ffmpeg executable (default: ffmpeg)
-  --ffprobe-bin <path>            ffprobe executable (default: ffprobe)
-`);
-      return 0;
-    }
-
-    if (!opts.inputVideo) {
-      stderr.write('Error: --input-video is required.\n');
-      return 1;
+const schema = {
+  options: {
+    'input': { type: 'string' as const },
+    'input-video': { type: 'string' as const },
+    'output': { type: 'string' as const },
+    'output-video': { type: 'string' as const },
+    'in-place': { type: 'boolean' as const, default: false },
+    'aspect': { type: 'string' as const },
+    'target-size': { type: 'string' as const },
+    'target-width': { type: 'string' as const },
+    'target-height': { type: 'string' as const },
+    'force': { type: 'boolean' as const, default: false },
+    'ffmpeg-bin': { type: 'string' as const, default: 'ffmpeg' },
+    'ffprobe-bin': { type: 'string' as const, default: 'ffprobe' },
+  },
+  allowPositionals: true,
+  usage: 'apltk enforce-video-aspect-ratio [options]',
+  description: 'Resize video output to a target aspect ratio or size.',
+  handler: async (
+    values: Record<string, unknown>,
+    positionals: string[],
+    context: ToolContext,
+  ): Promise<number> => {
+    const stdout = context.stdout || process.stdout;
+
+    const inputVideo = (values['input'] as string | undefined) ||
+      (values['input-video'] as string | undefined) ||
+      positionals[0] ||
+      null;
+
+    const outputVideo = (values['output'] as string | undefined) ||
+      (values['output-video'] as string | undefined) ||
+      null;
+
+    const inPlace = !!values['in-place'];
+    const targetSize = (values['target-size'] as string | undefined) ?? null;
+    const targetWidthVal = values['target-width'] ? parseInt(values['target-width'] as string, 10) || null : null;
+    const targetHeightVal = values['target-height'] ? parseInt(values['target-height'] as string, 10) || null : null;
+    const aspect = (values['aspect'] as string | undefined) ?? null;
+    const force = !!values['force'];
+    const ffmpegBin = (values['ffmpeg-bin'] as string) || 'ffmpeg';
+    const ffprobeBin = (values['ffprobe-bin'] as string) || 'ffprobe';
+
+    if (!inputVideo) {
+      throw new UserInputError('--input-video is required.');
     }
 
-    const inputPath = path.resolve(opts.inputVideo);
+    const inputPath = path.resolve(inputVideo);
     if (!fs.existsSync(inputPath)) {
-      stderr.write(`Error: Input video not found: ${inputPath}\n`);
-      return 1;
+      throw new UserInputError(`Input video not found: ${inputPath}`);
     }
 
-    if (opts.inPlace && opts.outputVideo) {
-      stderr.write('Error: Do not pass --output-video with --in-place.\n');
-      return 1;
+    if (inPlace && outputVideo) {
+      throw new UserInputError('Do not pass --output-video with --in-place.');
     }
 
     // Validate ffmpeg/ffprobe availability
     try {
-      execSync(`which ${opts.ffmpegBin}`, { stdio: 'ignore' });
-      execSync(`which ${opts.ffprobeBin}`, { stdio: 'ignore' });
+      execSync(`which ${ffmpegBin}`, { stdio: 'ignore' });
+      execSync(`which ${ffprobeBin}`, { stdio: 'ignore' });
     } catch {
-      stderr.write(`Error: Missing required commands: ${opts.ffmpegBin}, ${opts.ffprobeBin}\n`);
-      return 1;
+      throw new UserInputError(`Missing required commands: ${ffmpegBin}, ${ffprobeBin}`);
     }
 
-    const inputSize = probeVideoSize(inputPath, opts.ffprobeBin);
+    const inputSize = probeVideoSize(inputPath, ffprobeBin);
 
     // Resolve target dimensions
     let targetWidth: number;
     let targetHeight: number;
 
-    if (opts.aspect) {
+    if (aspect) {
       // Derive from aspect ratio based on input dimensions
-      const ratio = parseRatio(opts.aspect);
+      const ratio = parseRatio(aspect);
       const inputWider = inputSize.width * ratio.height > inputSize.height * ratio.width;
 
       if (inputWider) {
@@ -268,7 +189,7 @@ Options:
       targetWidth = evenFloor(targetWidth);
       targetHeight = evenFloor(targetHeight);
     } else {
-      const target = resolveTargetSize(opts);
+      const target = resolveTargetSize(targetSize, targetWidthVal, targetHeightVal);
       targetWidth = target.width;
       targetHeight = target.height;
     }
@@ -277,26 +198,24 @@ Options:
     let outputPath: string;
     let replaceInPlace = false;
 
-    if (opts.inPlace) {
+    if (inPlace) {
       outputPath = path.join(
         path.dirname(inputPath),
         `.tmp_${path.basename(inputPath)}`,
       );
       replaceInPlace = true;
-    } else if (opts.outputVideo) {
-      outputPath = path.resolve(opts.outputVideo);
+    } else if (outputVideo) {
+      outputPath = path.resolve(outputVideo);
       if (outputPath === inputPath) {
-        stderr.write('Error: Output path equals input path. Use --in-place to replace the input file.\n');
-        return 1;
+        throw new UserInputError('Output path equals input path. Use --in-place to replace the input file.');
       }
     } else {
       const parsed = path.parse(inputPath);
       outputPath = path.join(parsed.dir, `${parsed.name}_aspect_fixed.mp4`);
     }
 
-    if (!replaceInPlace && fs.existsSync(outputPath) && !opts.force) {
-      stderr.write(`Error: Output already exists: ${outputPath}. Use --force to overwrite.\n`);
-      return 1;
+    if (!replaceInPlace && fs.existsSync(outputPath) && !force) {
+      throw new UserInputError(`Output already exists: ${outputPath}. Use --force to overwrite.`);
     }
 
     const { filter, cropApplied } = buildVideoFilter(
@@ -321,10 +240,10 @@ Options:
     fs.mkdirSync(path.dirname(outputPath), { recursive: true });
 
     const ffmpegCmd = [
-      opts.ffmpegBin,
+      ffmpegBin,
       '-hide_banner',
       '-loglevel', 'error',
-      opts.force || replaceInPlace ? '-y' : '-n',
+      force || replaceInPlace ? '-y' : '-n',
       '-i', inputPath,
       '-vf', filter,
       '-map', '0:v:0',
@@ -342,7 +261,7 @@ Options:
     } catch (err: unknown) {
       if (replaceInPlace && fs.existsSync(outputPath)) fs.unlinkSync(outputPath);
       const msg = err instanceof Error ? err.message : 'unknown error';
-      throw new Error(`ffmpeg failed: ${msg}`);
+      throw new SystemError(`ffmpeg failed: ${msg}`, undefined, { cause: err });
     }
 
     if (replaceInPlace) {
@@ -350,7 +269,7 @@ Options:
       outputPath = inputPath;
     }
 
-    const finalSize = probeVideoSize(outputPath, opts.ffprobeBin);
+    const finalSize = probeVideoSize(outputPath, ffprobeBin);
     stdout.write(
       `[OK] Processed video written: ${outputPath}\n` +
       `[INFO] Input size: ${inputSize.width}x${inputSize.height}\n` +
@@ -360,16 +279,12 @@ Options:
     );
 
     return 0;
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : 'Unknown error';
-    stderr.write(`Error: ${msg}\n`);
-    return 1;
-  }
-}
+  },
+};
 
 export const tool: ToolDefinition = {
   name: 'enforce-video-aspect-ratio',
   category: 'media',
   description: 'Resize video output to a target aspect ratio or size.',
-  handler: enforceVideoAspectRatioHandler,
+  handler: createToolRunner(schema),
 };

package/packages/tools/enforce-video-aspect-ratio/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-enforce-video-aspect-ratio",
-  "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/eval/dist/index.js

@@ -24,6 +24,13 @@ import { scoreAllTests } from './scorer.js';
 import { generateReport, writeReport } from './reporter.js';
 import { loadAllScores, extractIssues, deduplicateIssues, generateSuggestedFix, generateOptimizationPlan, optimizeSkillMd, } from './optimizer.js';
 import { promisePool } from './lib/promise-pool.js';
+// ╔══════════════════════════════════════════════════════════════════════════╗
+// ║  SCOPE EXCLUSION NOTICE                                                ║
+// ║  This tool is explicitly excluded from the CLI refactoring scope       ║
+// ║  (SPEC.md L28). It predates createToolRunner, AppError, and            ║
+// ║  PlatformAdapter. DO NOT use this tool's patterns as a template        ║
+// ║  for new tools. New tools should use createToolRunner + AppError.      ║
+// ╚══════════════════════════════════════════════════════════════════════════╝
 // ─── Helpers ────────────────────────────────────────────────────────────────
 /**
  * Resolve the project root directory.