@laitszkin/apollo-toolkit 4.1.4 → 5.0.0

package/packages/tools/create-review-report/index.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { UserInputError, createToolRunner } from '@laitszkin/tool-utils';
 
 const TEMPLATE_RELATIVE_PATH = 'skills/review/assets/templates/REPORT.md';
 const OUTPUT_FILENAME = 'REPORT.md';
@@ -13,13 +14,12 @@ function hasSpecFile(dirPath: string): boolean {
   return SPEC_FILENAMES.some((name) => fs.existsSync(path.join(dirPath, name)));
 }
 
-function resolveTargetDir(inputPath: string, stderr: { write(msg: string): boolean }): string | null {
+function resolveTargetDir(inputPath: string): string {
   let stat: fs.Stats;
   try {
     stat = fs.statSync(inputPath);
   } catch {
-    stderr.write(`Error: Path not found: ${inputPath}\n`);
-    return null;
+    throw new UserInputError(`Path not found: ${inputPath}`);
   }
 
   // If it's a file, use its parent directory
@@ -30,12 +30,10 @@ function resolveTargetDir(inputPath: string, stderr: { write(msg: string): boole
   try {
     dirStat = fs.statSync(dir);
   } catch {
-    stderr.write(`Error: Directory not found: ${dir}\n`);
-    return null;
+    throw new UserInputError(`Directory not found: ${dir}`);
   }
   if (!dirStat.isDirectory()) {
-    stderr.write(`Error: Not a directory: ${dir}\n`);
-    return null;
+    throw new UserInputError(`Not a directory: ${dir}`);
   }
 
   const parentDir = path.dirname(dir);
@@ -50,8 +48,7 @@ function resolveTargetDir(inputPath: string, stderr: { write(msg: string): boole
     return parentDir;
   }
 
-  stderr.write(`Error: ${dir} is not a valid spec directory (no SPEC.md found).\n`);
-  return null;
+  throw new UserInputError(`${dir} is not a valid spec directory (no SPEC.md found).`);
 }
 
 function findLatestDateDir(baseDir: string): string | null {
@@ -66,17 +63,15 @@ function findLatestDateDir(baseDir: string): string | null {
   return dateDirs.length > 0 ? dateDirs[0] : null;
 }
 
-function autoDetectTargetDir(stderr: { write(msg: string): boolean }): string | null {
+function autoDetectTargetDir(): string {
   const plansDir = path.resolve(PLANS_DIR);
   if (!fs.existsSync(plansDir)) {
-    stderr.write(`Error: No ${PLANS_DIR}/ directory found. Specify the spec path manually.\n`);
-    return null;
+    throw new UserInputError(`No ${PLANS_DIR}/ directory found. Specify the spec path manually.`);
   }
 
   const latestDate = findLatestDateDir(plansDir);
   if (!latestDate) {
-    stderr.write(`Error: No dated spec directories found in ${PLANS_DIR}/. Specify the spec path manually.\n`);
-    return null;
+    throw new UserInputError(`No dated spec directories found in ${PLANS_DIR}/. Specify the spec path manually.`);
   }
 
   const datePath = path.join(plansDir, latestDate);
@@ -110,11 +105,11 @@ function autoDetectTargetDir(stderr: { write(msg: string): boolean }): string |
   }
 
   if (batchDirs.length > 1) {
-    stderr.write(`Error: Multiple batch specs found in ${datePath}. Specify the path manually:\n`);
+    let msg = `Multiple batch specs found in ${datePath}. Specify the path manually:`;
     for (const bd of batchDirs) {
-      stderr.write(`  apltk create-review-report ${bd.path}\n`);
+      msg += `\n  apltk create-review-report ${bd.path}`;
     }
-    return null;
+    throw new UserInputError(msg);
   }
 
   if (singleSpecs.length === 1) {
@@ -122,83 +117,59 @@ function autoDetectTargetDir(stderr: { write(msg: string): boolean }): string |
   }
 
   if (singleSpecs.length > 1) {
-    stderr.write(`Error: Multiple specs found in ${datePath}. Specify the path manually:\n`);
+    let msg = `Multiple specs found in ${datePath}. Specify the path manually:`;
     for (const ss of singleSpecs) {
-      stderr.write(`  apltk create-review-report ${ss.path}\n`);
+      msg += `\n  apltk create-review-report ${ss.path}`;
     }
-    return null;
+    throw new UserInputError(msg);
   }
 
-  stderr.write(`Error: No specs found in ${datePath}.\n`);
-  return null;
+  throw new UserInputError(`No specs found in ${datePath}.`);
 }
 
-export async function createReviewReportHandler(args: string[], context: ToolContext): Promise<number> {
-  const stdout = context.stdout || process.stdout;
-  const stderr = context.stderr || process.stderr;
-  const sourceRoot = context.sourceRoot || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
-
-  if (args.includes('--help') || args.includes('-h')) {
-    stdout.write(`Usage: apltk create-review-report [options] [<spec-path>]
-
-Copy the review report template (REPORT.md)
-to the appropriate spec directory.
+const schema = {
+  options: {
+    force: { type: 'boolean' as const, short: 'f' },
+  },
+  allowPositionals: true,
+  usage: 'apltk create-review-report [options] [<spec-path>]',
+  description: 'Copy the code review report template (REPORT.md) to the spec directory.',
+  handler: async (
+    values: Record<string, unknown>,
+    positionals: string[],
+    context: ToolContext,
+  ): Promise<number> => {
+    const stdout = context.stdout || process.stdout;
+    const sourceRoot = context.sourceRoot || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+
+    const force = values.force === true;
+
+    // Resolve template path
+    const templatePath = path.join(sourceRoot, TEMPLATE_RELATIVE_PATH);
+    if (!fs.existsSync(templatePath)) {
+      throw new UserInputError(`Review report template not found: ${templatePath}`);
+    }
 
-Positional:
-  <spec-path>    Path to the spec directory, spec.md file, or batch root.
-                 If omitted, auto-detects the latest spec in docs/plans/.
+    // Resolve target directory
+    const targetDir = positionals.length > 0
+      ? resolveTargetDir(path.resolve(positionals[0]))
+      : autoDetectTargetDir();
 
-Options:
-  --force, -f    Overwrite existing REPORT.md if it exists
-  --help, -h     Show this help message
+    // Copy template
+    const outputPath = path.join(targetDir, OUTPUT_FILENAME);
+    if (fs.existsSync(outputPath) && !force) {
+      throw new UserInputError(`${outputPath} already exists. Use --force to overwrite.`);
+    }
 
-Examples:
-  apltk create-review-report
-  apltk create-review-report docs/plans/2026-05-21/my-feature
-  apltk create-review-report docs/plans/2026-05-21/my-batch
-  apltk create-review-report --force
-`);
+    fs.copyFileSync(templatePath, outputPath);
+    stdout.write(`${outputPath}\n`);
     return 0;
-  }
-
-  const force = args.includes('--force') || args.includes('-f');
-  const positionalArgs = args.filter((a) => !a.startsWith('--'));
-
-  // Resolve template path
-  const templatePath = path.join(sourceRoot, TEMPLATE_RELATIVE_PATH);
-  if (!fs.existsSync(templatePath)) {
-    stderr.write(`Error: Review report template not found: ${templatePath}\n`);
-    return 1;
-  }
-
-  // Resolve target directory
-  let targetDir: string | null = null;
-
-  if (positionalArgs.length > 0) {
-    targetDir = resolveTargetDir(path.resolve(positionalArgs[0]), stderr);
-  } else {
-    targetDir = autoDetectTargetDir(stderr);
-  }
-
-  if (!targetDir) {
-    return 1;
-  }
-
-  // Copy template
-  const outputPath = path.join(targetDir, OUTPUT_FILENAME);
-  if (fs.existsSync(outputPath) && !force) {
-    stderr.write(`Error: ${outputPath} already exists. Use --force to overwrite.\n`);
-    return 1;
-  }
-
-  fs.copyFileSync(templatePath, outputPath);
-  stdout.write(`${outputPath}\n`);
-  return 0;
-}
+  },
+};
 
 export const tool: ToolDefinition = {
   name: 'create-review-report',
   category: 'Planning & architecture',
   description: 'Copy the code review report template (REPORT.md) to the spec directory.',
-  handler: createReviewReportHandler,
+  handler: createToolRunner(schema),
 };

package/packages/tools/create-review-report/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-create-review-report",
-  "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/create-specs/dist/index.d.ts

@@ -1,3 +1,2 @@
-import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
-export declare function createSpecsHandler(args: string[], context: ToolContext): Promise<number>;
+import type { ToolDefinition } from '@laitszkin/tool-registry';
 export declare const tool: ToolDefinition;

package/packages/tools/create-specs/dist/index.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { UserInputError, createToolRunner } from '../../../tool-utils/dist/index.js';
 const TEMPLATE_FILENAMES = ['SPEC.md'];
 const PLACEHOLDER_NAMES = ['[Feature Name]', '[功能名稱]'];
 function slugify(text) {
@@ -21,137 +22,83 @@ function renderContent(content, today, featureName, changeName, batchName) {
     rendered = rendered.replace(/\[batch_name\]/g, batchName || 'None');
     return rendered;
 }
-export async function createSpecsHandler(args, context) {
-    const stderr = context.stderr || process.stderr;
-    // Parse CLI args manually for portability (no argparse dependency)
-    const parsed = {};
-    const positionalArgs = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg.startsWith('--')) {
-            const eqIndex = arg.indexOf('=');
-            let key;
-            let value;
-            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;
-                }
-            }
-            if (key === 'force') {
-                parsed[key] = value === true || value === 'true';
-            }
-            else if (key === 'change-name' || key === 'slug') {
-                parsed['change-name'] = String(value);
-            }
-            else if (key === 'batch-name') {
-                parsed['batch-name'] = String(value);
-            }
-            else if (key === 'output-dir') {
-                parsed['output-dir'] = String(value);
-            }
-            else if (key === 'template-dir') {
-                parsed['template-dir'] = String(value);
-            }
-            else if (key === 'help' || key === 'h') {
-                parsed['help'] = true;
-            }
-        }
-        else {
-            positionalArgs.push(arg);
-        }
-    }
-    if (parsed['help']) {
-        const stdout = context.stdout || process.stdout;
-        stdout.write(`Usage: apltk create-specs <feature_name> [options]
-
-The tool auto-creates a <today> folder under --output-dir. Batch names
+const schema = {
+    options: {
+        'batch-name': { type: 'string' },
+        'change-name': { type: 'string' },
+        'slug': { type: 'string' },
+        'output-dir': { type: 'string', default: 'docs/plans' },
+        'template-dir': { type: 'string' },
+        'force': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    usage: 'apltk create-specs <feature_name> [options]',
+    description: `The tool auto-creates a <today> folder under --output-dir. Batch names
 should group related specs (e.g. "membership-cutover"), NOT include date
 prefixes like "2026-05-22-membership" — that produces nested date folders.
 
 Output:
   Single spec:  <output-dir>/<today>/<change-name>/SPEC.md
-  Batch:        <output-dir>/<today>/<batch-name>/<change-name>/SPEC.md
-
-Options:
-  --change-name, --slug   Folder name (defaults to slugified feature_name)
-  --batch-name            Batch folder name (do NOT include date prefix)
-  --output-dir            Output base directory (default: docs/plans)
-  --template-dir          Template directory
-  --force                 Overwrite existing files
-`);
+  Batch:        <output-dir>/<today>/<batch-name>/<change-name>/SPEC.md`,
+    handler: async (values, positionals, context) => {
+        const stderr = context.stderr ?? process.stderr;
+        const featureName = (positionals[0] || '').trim();
+        if (!featureName) {
+            throw new UserInputError('feature_name is required.');
+        }
+        const changeName = (values['change-name'] || values['slug'] || '').trim() || slugify(featureName);
+        if (!changeName) {
+            throw new UserInputError('Unable to build change_name. Provide --change-name with ASCII letters/numbers.');
+        }
+        const batchName = values['batch-name']?.trim() || null;
+        // Warn if batch name looks like it starts with a date (common agent mistake
+        // that produces nested date folders like <today>/2026-05-22-my-batch/).
+        if (batchName && /^\d{4}-\d{2}-\d{2}/.test(batchName)) {
+            stderr.write(`Warning: --batch-name "${batchName}" starts with a date pattern. The tool already\n`);
+            stderr.write(`creates a <today> folder automatically, so this will produce nested date folders.\n`);
+            stderr.write(`Use a descriptive name without date prefix, e.g. --batch-name "membership-cutover".\n\n`);
+        }
+        // Resolve template directory
+        const sourceRoot = context.sourceRoot || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+        const templateDirRaw = values['template-dir'] || path.join(sourceRoot, 'skills', 'spec', 'assets', 'templates');
+        const templateDir = path.resolve(templateDirRaw);
+        if (!fs.existsSync(templateDir)) {
+            throw new UserInputError(`Template directory not found: ${templateDir}`);
+        }
+        // Check template files exist
+        const missingTemplates = TEMPLATE_FILENAMES.filter((name) => !fs.existsSync(path.join(templateDir, name)));
+        if (missingTemplates.length > 0) {
+            throw new UserInputError(`Missing template files in ${templateDir}: ${missingTemplates.join(', ')}`);
+        }
+        const outputDir = path.resolve(values['output-dir'] || 'docs/plans');
+        const today = new Date().toISOString().slice(0, 10);
+        // Prevent double-nesting: if outputDir's last component is already today's date,
+        // use it directly as the date root rather than appending the date again.
+        const dateRoot = path.basename(outputDir) === today ? outputDir : path.join(outputDir, today);
+        const batchRoot = batchName ? path.join(dateRoot, batchName) : null;
+        const outputRoot = batchRoot ? path.join(batchRoot, changeName) : path.join(dateRoot, changeName);
+        const outputPaths = TEMPLATE_FILENAMES.map((name) => path.join(outputRoot, name));
+        const force = values['force'] === true;
+        const existingFiles = outputPaths.filter((p) => fs.existsSync(p));
+        if (existingFiles.length > 0 && !force) {
+            throw new UserInputError(`Files already exist: ${existingFiles.join(', ')}. Use --force to overwrite.`);
+        }
+        fs.mkdirSync(outputRoot, { recursive: true });
+        const stdout = context.stdout ?? process.stdout;
+        const todayStr = today;
+        for (const filename of TEMPLATE_FILENAMES) {
+            const templatePath = path.join(templateDir, filename);
+            const outputPath = path.join(outputRoot, filename);
+            const content = fs.readFileSync(templatePath, 'utf-8');
+            fs.writeFileSync(outputPath, renderContent(content, todayStr, featureName, changeName, batchName), 'utf-8');
+            stdout.write(`${outputPath}\n`);
+        }
         return 0;
-    }
-    const featureName = (positionalArgs[0] || '').trim();
-    if (!featureName) {
-        stderr.write('Error: feature_name is required.\n');
-        return 1;
-    }
-    const changeName = parsed['change-name']?.trim() || slugify(featureName);
-    if (!changeName) {
-        stderr.write('Error: Unable to build change_name. Provide --change-name with ASCII letters/numbers.\n');
-        return 1;
-    }
-    const batchName = parsed['batch-name']?.trim() || null;
-    // Warn if batch name looks like it starts with a date (common agent mistake
-    // that produces nested date folders like <today>/2026-05-22-my-batch/).
-    if (batchName && /^\d{4}-\d{2}-\d{2}/.test(batchName)) {
-        stderr.write(`Warning: --batch-name "${batchName}" starts with a date pattern. The tool already\n`);
-        stderr.write(`creates a <today> folder automatically, so this will produce nested date folders.\n`);
-        stderr.write(`Use a descriptive name without date prefix, e.g. --batch-name "membership-cutover".\n\n`);
-    }
-    // Resolve template directory
-    const sourceRoot = context.sourceRoot || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
-    const templateDirRaw = parsed['template-dir'] || path.join(sourceRoot, 'skills', 'spec', 'assets', 'templates');
-    const templateDir = path.resolve(templateDirRaw);
-    if (!fs.existsSync(templateDir)) {
-        stderr.write(`Error: Template directory not found: ${templateDir}\n`);
-        return 1;
-    }
-    // Check template files exist
-    const missingTemplates = TEMPLATE_FILENAMES.filter((name) => !fs.existsSync(path.join(templateDir, name)));
-    if (missingTemplates.length > 0) {
-        stderr.write(`Error: Missing template files in ${templateDir}: ${missingTemplates.join(', ')}\n`);
-        return 1;
-    }
-    const outputDir = path.resolve(parsed['output-dir'] || 'docs/plans');
-    const today = new Date().toISOString().slice(0, 10);
-    // Prevent double-nesting: if outputDir's last component is already today's date,
-    // use it directly as the date root rather than appending the date again.
-    const dateRoot = path.basename(outputDir) === today ? outputDir : path.join(outputDir, today);
-    const batchRoot = batchName ? path.join(dateRoot, batchName) : null;
-    const outputRoot = batchRoot ? path.join(batchRoot, changeName) : path.join(dateRoot, changeName);
-    const outputPaths = TEMPLATE_FILENAMES.map((name) => path.join(outputRoot, name));
-    const force = parsed['force'] === true;
-    const existingFiles = outputPaths.filter((p) => fs.existsSync(p));
-    if (existingFiles.length > 0 && !force) {
-        stderr.write(`Error: Files already exist: ${existingFiles.join(', ')}. Use --force to overwrite.\n`);
-        return 1;
-    }
-    fs.mkdirSync(outputRoot, { recursive: true });
-    const stdout = context.stdout || process.stdout;
-    const todayStr = today;
-    for (const filename of TEMPLATE_FILENAMES) {
-        const templatePath = path.join(templateDir, filename);
-        const outputPath = path.join(outputRoot, filename);
-        const content = fs.readFileSync(templatePath, 'utf-8');
-        fs.writeFileSync(outputPath, renderContent(content, todayStr, featureName, changeName, batchName), 'utf-8');
-        stdout.write(`${outputPath}\n`);
-    }
-    return 0;
-}
+    },
+};
 export const tool = {
     name: 'create-specs',
     category: 'Planning & architecture',
     description: 'Create spec planning documents from templates.',
-    handler: createSpecsHandler,
+    handler: createToolRunner(schema),
 };