@laitszkin/apollo-toolkit 4.1.4 → 5.0.1

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

@@ -1,6 +1,16 @@
+/*
+ * review-threads — Carryover tool migrated from the pre-monorepo CLI
+ * architecture (originally resolve-review-comments/scripts/review_threads.py).
+ *
+ * Carryover status (Round 16, 2026-06-06):
+ * - Added --help/-h support for subcommand-based usage.
+ * - Stdout/stderr invariant: resolved data -> stdout, failures -> stderr.
+ */
+
 import { execFile } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { UserInputError, SystemError } from '@laitszkin/tool-utils';
 
 const LIST_QUERY = `
 query($owner: String!, $name: String!, $number: Int!, $after: String) {
@@ -60,6 +70,7 @@ interface ReviewThreadsArgs {
   threadIdFile: string | null;
   allUnresolved: boolean;
   dryRun: boolean;
+  help: boolean;
 }
 
 function parseArgs(argv: string[]): ReviewThreadsArgs {
@@ -73,8 +84,15 @@ function parseArgs(argv: string[]): ReviewThreadsArgs {
     threadIdFile: null,
     allUnresolved: false,
     dryRun: false,
+    help: false,
   };
 
+  // Check for --help/-h before positional parsing
+  if (argv.includes('--help') || argv.includes('-h')) {
+    args.help = true;
+    return args;
+  }
+
   // First argument is the subcommand (list/resolve)
   let i = 0;
   if (i < argv.length && !argv[i].startsWith('-')) {
@@ -158,12 +176,12 @@ function runGh(cmdArgs: string[]): Promise<CommandResult> {
 function runGhJson(cmdArgs: string[]): Promise<Record<string, unknown>> {
   return runGh(cmdArgs).then((result) => {
     if (result.exitCode !== 0) {
-      throw new Error(result.stderr.trim() || 'gh command failed');
+      throw new SystemError(result.stderr.trim() || 'gh command failed');
     }
     try {
       return JSON.parse(result.stdout);
     } catch (exc) {
-      throw new Error('Failed to parse gh JSON output');
+      throw new SystemError('Failed to parse gh JSON output', undefined, { cause: exc });
     }
   });
 }
@@ -171,7 +189,7 @@ function runGhJson(cmdArgs: string[]): Promise<Record<string, unknown>> {
 function parseOwnerRepo(repo: string): [string, string] {
   const parts = repo.split('/');
   if (parts.length !== 2 || !parts[0] || !parts[1]) {
-    throw new Error('repo must be in owner/name format');
+    throw new UserInputError('repo must be in owner/name format');
   }
   return [parts[0], parts[1]];
 }
@@ -191,7 +209,7 @@ async function resolveRepo(repo: string | null): Promise<string> {
     '.nameWithOwner',
   ]);
   if (result.exitCode !== 0) {
-    throw new Error(result.stderr.trim() || 'Unable to resolve current repo');
+    throw new SystemError(result.stderr.trim() || 'Unable to resolve current repo');
   }
   return result.stdout.trim();
 }
@@ -210,7 +228,7 @@ async function resolvePrNumber(repo: string, pr: number | null): Promise<number>
     '.number',
   ]);
   if (result.exitCode !== 0) {
-    throw new Error(
+    throw new UserInputError(
       'Unable to infer PR number from current branch context',
     );
   }
@@ -248,7 +266,7 @@ async function fetchReviewThreads(
 
     const pr = (payload.data as Record<string, unknown>)?.repository as Record<string, unknown> | undefined;
     if (!pr) {
-      throw new Error(`PR #${prNumber} not found in ${repo}`);
+      throw new UserInputError(`PR #${prNumber} not found in ${repo}`);
     }
 
     const reviewThreads = pr.reviewThreads as Record<string, unknown>;
@@ -381,12 +399,12 @@ function loadThreadIds(filePath: string): string[] {
         .map((item) => item.thread_id)
         .filter((id) => id !== undefined);
     } else {
-      throw new Error(
+      throw new UserInputError(
         'JSON must include thread_ids, adopted_thread_ids, or threads',
       );
     }
   } else {
-    throw new Error('Unsupported JSON payload for thread IDs');
+    throw new UserInputError('Unsupported JSON payload for thread IDs');
   }
 
   const output = ids
@@ -438,11 +456,11 @@ async function resolveThreads(
         payload.data as Record<string, unknown>
       )?.resolveReviewThread as Record<string, unknown> | undefined;
       if (!thread?.thread) {
-        throw new Error('thread did not resolve');
+        throw new SystemError('thread did not resolve');
       }
       const resolvedThread = thread.thread as Record<string, unknown>;
       if (!resolvedThread.isResolved) {
-        throw new Error('thread did not resolve');
+        throw new SystemError('thread did not resolve');
       }
       resolved.push(threadId);
     } catch (exc) {
@@ -459,31 +477,11 @@ async function cmdList(
   args: ReviewThreadsArgs,
   context: ToolContext,
 ): Promise<number> {
-  const { stdout, stderr } = context;
-
-  let repo: string;
-  try {
-    repo = await resolveRepo(args.repo);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
-
-  let prNumber: number;
-  try {
-    prNumber = await resolvePrNumber(repo, args.pr);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
+  const { stdout } = context;
 
-  let threads: Array<Record<string, unknown>>;
-  try {
-    threads = await fetchReviewThreads(repo, prNumber);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
+  const repo = await resolveRepo(args.repo);
+  const prNumber = await resolvePrNumber(repo, args.pr);
+  const threads: Array<Record<string, unknown>> = await fetchReviewThreads(repo, prNumber);
 
   const filtered = filterThreads(threads, args.state);
   const normalized = filtered.map(normalizeThread);
@@ -512,79 +510,87 @@ async function cmdResolve(
   args: ReviewThreadsArgs,
   context: ToolContext,
 ): Promise<number> {
-  const { stdout, stderr } = context;
-
-  let repo: string;
-  try {
-    repo = await resolveRepo(args.repo);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
+  const { stdout } = context;
 
-  let prNumber: number;
-  try {
-    prNumber = await resolvePrNumber(repo, args.pr);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
-
-  let threads: Array<Record<string, unknown>>;
-  try {
-    threads = await fetchReviewThreads(repo, prNumber);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
-  }
+  const repo = await resolveRepo(args.repo);
+  const prNumber = await resolvePrNumber(repo, args.pr);
+  const threads: Array<Record<string, unknown>> = await fetchReviewThreads(repo, prNumber);
 
   const unresolved = filterThreads(threads, 'unresolved').map(normalizeThread);
   const threadIds = collectThreadIds(args, unresolved);
 
   if (threadIds.length === 0) {
-    stderr!.write(
-      'Error: no thread IDs selected. Use --thread-id, --thread-id-file, or --all-unresolved.\n',
+    throw new UserInputError(
+      'no thread IDs selected. Use --thread-id, --thread-id-file, or --all-unresolved.',
     );
-    return 1;
   }
 
   const { resolved, failed } = await resolveThreads(threadIds, args.dryRun);
 
-  const summary = {
-    repo,
-    pr_number: prNumber,
-    requested: threadIds,
-    resolved,
-    failed,
-    dry_run: args.dryRun,
-  };
-  stdout!.write(JSON.stringify(summary, null, 2) + '\n');
+  stdout!.write(JSON.stringify({ resolved }, null, 2) + '\n');
+  context.stderr!.write(JSON.stringify({ failed }, null, 2) + '\n');
 
   return failed.length > 0 ? 1 : 0;
 }
 
+// ---- Help ----
+
+function printHelp(stdout: NodeJS.WriteStream): void {
+  stdout.write(`Usage: apltk review-threads <subcommand> [options]
+
+List or resolve GitHub PR review threads.
+
+Subcommands:
+  list       List review threads for a pull request
+  resolve    Resolve specific review threads
+
+Options:
+  --repo <owner/name>       GitHub repository (default: current repo)
+  --pr <number>             PR number (default: current branch's PR)
+  --state <unresolved|resolved|all>
+                            Filter threads by state (default: unresolved)
+  --output <table|json>     Output format for list (default: table)
+  --thread-id <id>          Thread ID to resolve (may be repeated)
+  --thread-id-file <path>   JSON file with thread IDs to resolve
+  --all-unresolved          Resolve all unresolved threads
+  --dry-run                 Simulate resolution without mutating
+  --help, -h                Show this help message
+`);
+}
+
 // ---- Main handler ----
 
+/**
+ * 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 async function reviewThreadsHandler(
   argv: string[],
   context: ToolContext,
 ): Promise<number> {
-  const { stderr } = context;
+  const { stdout } = context;
   const args = parseArgs(argv);
 
-  try {
-    switch (args.command) {
-      case 'list':
-        return await cmdList(args, context);
-      case 'resolve':
-        return await cmdResolve(args, context);
-      default:
-        stderr!.write(`Unsupported command: ${args.command}\n`);
-        return 1;
-    }
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
+  if (args.help) {
+    printHelp(stdout!);
+    return 0;
+  }
+
+  switch (args.command) {
+    case 'list':
+      return await cmdList(args, context);
+    case 'resolve':
+      return await cmdResolve(args, context);
+    default:
+      throw new UserInputError(`Unsupported command: ${args.command}`);
   }
 }
 

package/packages/tools/review-threads/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-review-threads",
-  "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",
@@ -18,5 +18,12 @@
   },
   "dependencies": {
     "@laitszkin/tool-registry": "*"
-  }
-}
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/packages/tools/search-logs/dist/index.js

@@ -1,75 +1,15 @@
-import { extractTimestamp, inWindow, iterInputLines, parseCliTimestamp, buildTimezone, validateTimeWindow, } from '../../../tool-utils/dist/index.js';
-function parseArgs(argv) {
-    const args = {
-        paths: [],
-        keyword: [],
-        regex: [],
-        mode: 'any',
-        ignoreCase: false,
-        start: null,
-        end: null,
-        assumeTimezone: 'UTC',
-        beforeContext: 0,
-        afterContext: 0,
-        countOnly: false,
-    };
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        if (arg === '--keyword' && i + 1 < argv.length) {
-            args.keyword.push(argv[++i]);
-        }
-        else if (arg === '--regex' && i + 1 < argv.length) {
-            args.regex.push(argv[++i]);
-        }
-        else if (arg === '--mode' && i + 1 < argv.length) {
-            const val = argv[++i];
-            if (val === 'any' || val === 'all') {
-                args.mode = val;
-            }
-        }
-        else if (arg === '--ignore-case') {
-            args.ignoreCase = true;
-        }
-        else if (arg === '--start' && i + 1 < argv.length) {
-            args.start = argv[++i];
-        }
-        else if (arg === '--end' && i + 1 < argv.length) {
-            args.end = argv[++i];
-        }
-        else if (arg === '--assume-timezone' && i + 1 < argv.length) {
-            args.assumeTimezone = argv[++i];
-        }
-        else if (arg === '--before-context' && i + 1 < argv.length) {
-            args.beforeContext = parseInt(argv[++i], 10) || 0;
-        }
-        else if (arg === '--after-context' && i + 1 < argv.length) {
-            args.afterContext = parseInt(argv[++i], 10) || 0;
-        }
-        else if (arg === '--count-only') {
-            args.countOnly = true;
-        }
-        else if (arg.startsWith('-')) {
-            // skip unknown flags
-        }
-        else {
-            args.paths.push(arg);
-        }
-        i++;
-    }
-    return args;
-}
-function buildMatchers(args) {
+import { UserInputError, SystemError, createToolRunner, extractTimestamp, inWindow, iterInputLines, parseCliTimestamp, buildTimezone, } from '../../../tool-utils/dist/index.js';
+function buildMatchers(keywords, regexPatterns, ignoreCase, mode) {
     const matchers = [];
-    for (const keyword of args.keyword) {
-        const needle = args.ignoreCase ? keyword.toLowerCase() : keyword;
+    for (const keyword of keywords) {
+        const needle = ignoreCase ? keyword.toLowerCase() : keyword;
         matchers.push((line) => {
-            const haystack = args.ignoreCase ? line.toLowerCase() : line;
+            const haystack = ignoreCase ? line.toLowerCase() : line;
             return haystack.includes(needle);
         });
     }
-    for (const pattern of args.regex) {
-        const flags = args.ignoreCase ? 'i' : '';
+    for (const pattern of regexPatterns) {
+        const flags = ignoreCase ? 'i' : '';
         const compiled = new RegExp(pattern, flags);
         matchers.push((line) => compiled.test(line));
     }
@@ -83,86 +23,110 @@ function lineMatches(line, matchers, mode) {
     }
     return matchers.every((m) => m(line));
 }
-async function searchLogsHandler(argv, context) {
-    const stdout = context.stdout ?? process.stdout;
-    const stderr = context.stderr ?? process.stderr;
-    const args = parseArgs(argv);
-    try {
-        buildTimezone(args.assumeTimezone);
-    }
-    catch (err) {
-        stderr.write(`Error: invalid timezone: ${args.assumeTimezone}\n`);
-        return 1;
-    }
-    let start = null;
-    let end = null;
-    try {
-        if (args.start) {
-            start = parseCliTimestamp(args.start, args.assumeTimezone);
+const schema = {
+    options: {
+        keyword: { type: 'string', multiple: true },
+        regex: { type: 'string', multiple: true },
+        mode: { type: 'string', default: 'any' },
+        'ignore-case': { type: 'boolean', default: false },
+        start: { type: 'string' },
+        end: { type: 'string' },
+        'assume-timezone': { type: 'string', default: 'UTC' },
+        'before-context': { type: 'string', default: '0' },
+        'after-context': { type: 'string', default: '0' },
+        'count-only': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+    usage: 'apltk search-logs [options] [<file>...]',
+    description: 'Search log lines by keywords or regex patterns with time filters',
+    handler: async (values, positionals, context) => {
+        const stdout = context.stdout ?? process.stdout;
+        const mode = values.mode;
+        if (mode !== 'any' && mode !== 'all') {
+            throw new UserInputError('--mode must be "any" or "all"');
         }
-        if (args.end) {
-            end = parseCliTimestamp(args.end, args.assumeTimezone);
+        const keywords = values.keyword || [];
+        const regexPatterns = values.regex || [];
+        const ignoreCase = values['ignore-case'];
+        const assumeTimezone = values['assume-timezone'];
+        const beforeContext = parseInt(values['before-context'], 10) || 0;
+        const afterContext = parseInt(values['after-context'], 10) || 0;
+        const countOnly = values['count-only'];
+        try {
+            buildTimezone(assumeTimezone);
         }
-    }
-    catch (err) {
-        stderr.write(`Error: ${err.message}\n`);
-        return 1;
-    }
-    if (!validateTimeWindow(start, end, stderr)) {
-        return 1;
-    }
-    const matchers = buildMatchers(args);
-    let matches = 0;
-    const beforeBuffer = [];
-    let afterRemaining = 0;
-    try {
-        for await (const line of iterInputLines(args.paths)) {
-            const timestamp = extractTimestamp(line, args.assumeTimezone);
-            // When time filter is active, skip lines outside the window
-            if (args.start || args.end) {
-                if (!inWindow(timestamp, start, end)) {
-                    beforeBuffer.push(line);
-                    if (beforeBuffer.length > args.beforeContext) {
-                        beforeBuffer.shift();
+        catch {
+            throw new UserInputError(`invalid timezone: ${assumeTimezone}`);
+        }
+        let start = null;
+        let end = null;
+        try {
+            if (values.start) {
+                start = parseCliTimestamp(values.start, assumeTimezone);
+            }
+            if (values.end) {
+                end = parseCliTimestamp(values.end, assumeTimezone);
+            }
+        }
+        catch (err) {
+            throw new UserInputError(err.message);
+        }
+        if (start && end && start > end) {
+            throw new UserInputError('--start must be earlier than or equal to --end.');
+        }
+        const matchers = buildMatchers(keywords, regexPatterns, ignoreCase, mode);
+        let matches = 0;
+        const beforeBuffer = [];
+        let afterRemaining = 0;
+        try {
+            for await (const line of iterInputLines(positionals)) {
+                const timestamp = extractTimestamp(line, assumeTimezone);
+                // When time filter is active, skip lines outside the window
+                if (values.start || values.end) {
+                    if (!inWindow(timestamp, start, end)) {
+                        beforeBuffer.push(line);
+                        if (beforeBuffer.length > beforeContext) {
+                            beforeBuffer.shift();
+                        }
+                        continue;
                     }
-                    continue;
                 }
-            }
-            const isMatch = lineMatches(line, matchers, args.mode);
-            if (isMatch) {
-                matches++;
-                if (!args.countOnly) {
-                    // Flush before context
-                    for (const ctxLine of beforeBuffer) {
-                        stdout.write(ctxLine + '\n');
+                const isMatch = lineMatches(line, matchers, mode);
+                if (isMatch) {
+                    matches++;
+                    if (!countOnly) {
+                        // Flush before context
+                        for (const ctxLine of beforeBuffer) {
+                            stdout.write(ctxLine + '\n');
+                        }
+                        stdout.write(line + '\n');
                     }
+                    afterRemaining = afterContext;
+                }
+                else if (afterRemaining > 0 && !countOnly) {
                     stdout.write(line + '\n');
+                    afterRemaining--;
+                }
+                // Maintain before context buffer
+                beforeBuffer.push(line);
+                if (beforeBuffer.length > beforeContext) {
+                    beforeBuffer.shift();
                 }
-                afterRemaining = args.afterContext;
-            }
-            else if (afterRemaining > 0 && !args.countOnly) {
-                stdout.write(line + '\n');
-                afterRemaining--;
-            }
-            // Maintain before context buffer
-            beforeBuffer.push(line);
-            if (beforeBuffer.length > args.beforeContext) {
-                beforeBuffer.shift();
             }
         }
-    }
-    catch (err) {
-        stderr.write(`Error: ${err.message}\n`);
-        return 1;
-    }
-    if (args.countOnly) {
-        stdout.write(String(matches) + '\n');
-    }
-    return 0;
-}
+        catch (err) {
+            throw new SystemError(err.message);
+        }
+        if (countOnly) {
+            stdout.write(String(matches) + '\n');
+        }
+        return 0;
+    },
+};
 export const tool = {
     name: 'search-logs',
     category: 'Log Analysis',
     description: 'Search log lines by keywords or regex patterns with time filters',
-    handler: searchLogsHandler,
+    handler: createToolRunner(schema),
 };