@laitszkin/apollo-toolkit 4.1.4 → 5.0.0

package/packages/tools/open-github-issue/index.ts

@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
 import { join as joinPath } from 'node:path';
 import { cwd } from 'node:process';
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
+import { UserInputError, SystemError } from '@laitszkin/tool-utils';
 
 const GITHUB_API_BASE = 'https://api.github.com';
 const README_ACCEPT = 'application/vnd.github.raw+json';
@@ -76,6 +77,29 @@ const PAYLOAD_FIELDS = new Set([
   'dry_run',
 ]);
 
+const HELP_TEXT = `
+Usage: open-github-issue [options]
+
+Options:
+  --payload-file <path>          Path to JSON payload file with issue fields
+  --title <text>                 Issue title
+  --issue-type <type>            Issue type (problem|feature|performance|security|docs|observability)
+  --problem-description <text>   Description of the problem
+  --suspected-cause <text>       Suspected root cause
+  --reproduction <text>          Reproduction steps
+  --proposal <text>              Feature proposal description
+  --reason <text>                Reason for the feature
+  --suggested-architecture <text> Suggested architecture
+  --impact <text>                Impact description
+  --evidence <text>              Evidence supporting the issue
+  --suggested-action <text>      Suggested action
+  --severity <text>              Severity level (for security issues)
+  --affected-scope <text>        Affected scope
+  --repo <owner/repo>            Target repository (e.g., owner/repo)
+  --dry-run                      Validate and print issue body without publishing
+  --help, -h                     Show this help message
+`;
+
 interface OpenIssueArgs {
   payloadFile: string | null;
   title: string | null;
@@ -93,6 +117,7 @@ interface OpenIssueArgs {
   affectedScope: string | null;
   repo: string | null;
   dryRun: boolean;
+  helpRequested: boolean;
 }
 
 function parseArgs(argv: string[]): OpenIssueArgs {
@@ -113,6 +138,7 @@ function parseArgs(argv: string[]): OpenIssueArgs {
     affectedScope: null,
     repo: null,
     dryRun: false,
+    helpRequested: false,
   };
 
   let i = 0;
@@ -167,6 +193,10 @@ function parseArgs(argv: string[]): OpenIssueArgs {
       case '--dry-run':
         args.dryRun = true;
         break;
+      case '--help':
+      case '-h':
+        args.helpRequested = true;
+        break;
       default:
         if (!arg.startsWith('-')) {
           // unsupported positional — ignore per Python behavior
@@ -217,7 +247,7 @@ function readPayloadFile(rawPath: string): PayloadEntry {
 
   if (rawPath === '-') {
     // We cannot read stdin here easily; throw clear error
-    throw new Error('stdin payload (-) is not supported in handler mode; use a file path');
+    throw new UserInputError('stdin payload (-) is not supported in handler mode; use a file path');
   } else {
     rawContent = readFileSync(rawPath, 'utf-8');
     context = rawPath;
@@ -227,18 +257,18 @@ function readPayloadFile(rawPath: string): PayloadEntry {
   try {
     payload = JSON.parse(rawContent);
   } catch (exc) {
-    throw new Error(`Invalid JSON payload in ${context}: ${(exc as Error).message}`);
+    throw new UserInputError(`Invalid JSON payload in ${context}: ${(exc as Error).message}`, undefined, { cause: exc });
   }
 
   if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
-    throw new Error(`Invalid JSON payload in ${context}: top-level value must be an object.`);
+    throw new UserInputError(`Invalid JSON payload in ${context}: top-level value must be an object.`);
   }
 
   const normalized: PayloadEntry = {};
   for (const [rawKey, value] of Object.entries(payload as Record<string, unknown>)) {
     const key = normalizeKey(rawKey);
     if (!PAYLOAD_FIELDS.has(key)) {
-      throw new Error(`Unsupported payload key: ${rawKey}`);
+      throw new UserInputError(`Unsupported payload key: ${rawKey}`);
     }
     normalized[key] = value;
   }
@@ -249,15 +279,17 @@ function readAtFileValue(fieldName: string, value: string | null): string | null
   if (value == null) return null;
   if (value.startsWith('@@')) return value.slice(1);
   if (value === '@-') {
-    throw new Error('stdin reading (@-) is not supported in handler mode');
+    throw new UserInputError('stdin reading (@-) is not supported in handler mode');
   }
   if (value.startsWith('@') && value.length > 1) {
     const filePath = value.slice(1);
     try {
       return readFileSync(filePath, 'utf-8');
     } catch (exc) {
-      throw new Error(
+      throw new UserInputError(
         `Unable to read @${fieldName} file ${filePath}: ${(exc as Error).message}`,
+        undefined,
+        { cause: exc },
       );
     }
   }
@@ -266,7 +298,7 @@ function readAtFileValue(fieldName: string, value: string | null): string | null
 
 function requireNonEmpty(value: string | null | undefined, message: string): void {
   if (!(value || '').trim()) {
-    throw new Error(message);
+    throw new UserInputError(message);
   }
 }
 
@@ -288,7 +320,7 @@ function getToken(env: Record<string, string | undefined>): string | null {
 function validateRepo(repo: string): string {
   const candidate = repo.trim();
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(candidate)) {
-    throw new Error('Invalid repo format. Use owner/repo.');
+    throw new UserInputError('Invalid repo format. Use owner/repo.');
   }
   return candidate;
 }
@@ -607,7 +639,7 @@ async function createIssueWithGh(
     ]);
 
     if (result.exitCode !== 0) {
-      throw new Error(result.stderr.trim() || 'gh issue create failed');
+      throw new SystemError(result.stderr.trim() || 'gh issue create failed');
     }
 
     const urlMatch = result.stdout.match(
@@ -636,7 +668,7 @@ async function createIssueWithToken(
   const parsed = JSON.parse(response);
   const issueUrl: string | undefined = parsed.html_url;
   if (!issueUrl) {
-    throw new Error('Issue created but response did not include html_url');
+    throw new SystemError('Issue created but response did not include html_url');
   }
   return issueUrl;
 }
@@ -692,7 +724,7 @@ function validateIssueContent(args: OpenIssueArgs): void {
   requireNonEmpty(args.problemDescription, 'Problem issues require --problem-description.');
   requireNonEmpty(args.suspectedCause, 'Problem issues require --suspected-cause.');
   if (!hasRequiredProblemBddSections(args.problemDescription || '')) {
-    throw new Error(
+    throw new UserInputError(
       'Problem issues require --problem-description to include ' +
         'Expected Behavior (BDD), Current Behavior (BDD), and Behavior Gap sections.',
     );
@@ -708,7 +740,7 @@ function hydrateArgs(args: OpenIssueArgs): OpenIssueArgs {
     for (const [key, value] of Object.entries(payload)) {
       if (key === 'dry_run') {
         if (typeof value !== 'boolean') {
-          throw new Error("Payload field 'dry_run' must be a boolean.");
+          throw new UserInputError("Payload field 'dry_run' must be a boolean.");
         }
         if (!result.dryRun) {
           result.dryRun = value;
@@ -719,10 +751,10 @@ function hydrateArgs(args: OpenIssueArgs): OpenIssueArgs {
       // String fields
       if (TEXT_FIELDS.includes(key as (typeof TEXT_FIELDS)[number])) {
         if (value !== null && typeof value !== 'string') {
-          throw new Error(`Payload field '${key}' must be a string or null.`);
+          throw new UserInputError(`Payload field '${key}' must be a string or null.`);
         }
       } else if (typeof value !== 'string') {
-        throw new Error(`Payload field '${key}' must be a string.`);
+        throw new UserInputError(`Payload field '${key}' must be a string.`);
       }
 
       const currentVal = (result as Record<string, unknown>)[key];
@@ -737,7 +769,7 @@ function hydrateArgs(args: OpenIssueArgs): OpenIssueArgs {
     result.issueType = ISSUE_TYPE_PROBLEM;
   }
   if (!ISSUE_TYPES.includes(result.issueType as (typeof ISSUE_TYPES)[number])) {
-    throw new Error(`Invalid issue_type: ${result.issueType}`);
+    throw new UserInputError(`Invalid issue_type: ${result.issueType}`);
   }
 
   // Resolve @-prefixed file values
@@ -749,7 +781,7 @@ function hydrateArgs(args: OpenIssueArgs): OpenIssueArgs {
 
   // Title is required
   if (!(result.title || '').trim()) {
-    throw new Error('Issue title is required. Pass --title or include title in --payload-file.');
+    throw new UserInputError('Issue title is required. Pass --title or include title in --payload-file.');
   }
 
   return result;
@@ -764,10 +796,7 @@ async function resolveRepoAsync(
   // Try to resolve from git remote
   const result = await runCommand('git', ['remote', 'get-url', 'origin']);
   if (result.exitCode !== 0) {
-    context.stderr!.write(
-      'Unable to resolve origin remote. Pass --repo owner/repo.\n',
-    );
-    throw new Error('--repo resolution failed');
+    throw new UserInputError('Unable to resolve origin remote. Pass --repo owner/repo.');
   }
 
   const remote = result.stdout.trim();
@@ -775,10 +804,7 @@ async function resolveRepoAsync(
     /github\.com[:/](?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+?)(?:\.git)?$/,
   );
   if (!match?.groups) {
-    context.stderr!.write(
-      'Origin remote is not a GitHub repository. Pass --repo owner/repo.\n',
-    );
-    throw new Error('--repo resolution failed');
+    throw new UserInputError('Unable to resolve origin remote. Pass --repo owner/repo.');
   }
 
   return `${match.groups.owner}/${match.groups.repo}`;
@@ -797,30 +823,37 @@ interface IssueResult {
   publish_error: string;
 }
 
+/**
+ * openGitHubIssueHandler — Known carryover from createToolRunner migration.
+ *
+ * Reason for not using createToolRunner:
+ * - Positional subcommand architecture (create/draft) with 15+ tool-specific
+ *   flags doesn't map cleanly to createToolRunner's options schema.
+ * - Error handling follows the AppError convention (UserInputError/SystemError
+ *   throws) which is handled by the CLI boundary's formatAppError.
+ * - Argument parsing and help text are handled manually — 83-line parseArgs().
+ *
+ * See DESIGN.md §2.3 for the full architecture discussion.
+ * --help is now supported.
+ */
 export async function openGitHubIssueHandler(
   argv: string[],
   context: ToolContext,
 ): Promise<number> {
   const { stdout, stderr, env } = context;
 
-  let args: OpenIssueArgs;
-  try {
-    args = hydrateArgs(parseArgs(argv));
-    validateIssueContent(args);
-  } catch (err) {
-    stderr!.write(`Error: ${(err as Error).message}\n`);
-    return 1;
+  const parsed = parseArgs(argv);
+  if (parsed.helpRequested) {
+    stdout!.write(HELP_TEXT + '\n');
+    return 0;
   }
+  const args = hydrateArgs(parsed);
+  validateIssueContent(args);
 
   const ghAuthenticated = await hasGhAuth();
   const token = getToken(env || {});
 
-  let repo: string;
-  try {
-    repo = await resolveRepoAsync(args.repo, context);
-  } catch {
-    return 1;
-  }
+  const repo = await resolveRepoAsync(args.repo, context);
 
   const readmeContent = await fetchRemoteReadme(repo, ghAuthenticated, token);
   const language = detectIssueLanguage(readmeContent);
@@ -898,9 +931,7 @@ export async function openGitHubIssueHandler(
 
   if (mode === 'draft-only') {
     if (publishError) {
-      stderr!.write(
-        `Issue publish failed. Return draft only: ${publishError}\n`,
-      );
+      throw new SystemError(`Issue publish failed. Return draft only: ${publishError}`);
     } else {
       stderr!.write(
         'No authenticated gh CLI session and no GitHub token found. ' +
@@ -914,38 +945,6 @@ export async function openGitHubIssueHandler(
 
 // ---- Tool definition ----
 
-const FLAG_MAP: Record<string, { flag: string; type: 'string' | 'boolean' }> = {
-  payloadFile:         { flag: '--payload-file',          type: 'string' },
-  title:               { flag: '--title',                 type: 'string' },
-  issueType:           { flag: '--issue-type',            type: 'string' },
-  problemDescription:  { flag: '--problem-description',   type: 'string' },
-  suspectedCause:      { flag: '--suspected-cause',       type: 'string' },
-  reproduction:        { flag: '--reproduction',          type: 'string' },
-  proposal:            { flag: '--proposal',              type: 'string' },
-  reason:              { flag: '--reason',                type: 'string' },
-  suggestedArchitecture: { flag: '--suggested-architecture', type: 'string' },
-  impact:              { flag: '--impact',                type: 'string' },
-  evidence:            { flag: '--evidence',              type: 'string' },
-  suggestedAction:     { flag: '--suggested-action',      type: 'string' },
-  severity:            { flag: '--severity',              type: 'string' },
-  affectedScope:       { flag: '--affected-scope',        type: 'string' },
-  repo:                { flag: '--repo',                  type: 'string' },
-  dryRun:              { flag: '--dry-run',               type: 'boolean' },
-};
-
-function buildArgsFromYargs(argv: Record<string, unknown>): string[] {
-  const args: string[] = [];
-  for (const [camel, { flag, type }] of Object.entries(FLAG_MAP)) {
-    const value = argv[camel];
-    if (type === 'boolean') {
-      if (value) args.push(flag);
-    } else if (value !== undefined && value !== null) {
-      args.push(flag, String(value));
-    }
-  }
-  return args;
-}
-
 export const tool: ToolDefinition = {
   name: 'open-github-issue',
   category: 'GitHub workflows',

package/packages/tools/open-github-issue/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laitszkin/tool-open-github-issue",
-  "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/read-github-issue/dist/index.d.ts

@@ -1,3 +1,18 @@
 import type { ToolDefinition, ToolContext } from '@laitszkin/tool-registry';
-export declare function readGitHubIssueHandler(argv: string[], context: ToolContext): Promise<number>;
+interface ReadIssueArgs {
+    issue: string | null;
+    repo: string | null;
+    comments: boolean;
+    json: boolean;
+}
+/**
+ * readGitHubIssueHandler — Wrapped in createToolRunner for schema-based
+ * argument parsing. The schema (see tool export) declares --repo, --json,
+ * --comments, and --help. Positional <issue> argument comes via positionals[0].
+ *
+ * Error handling uses UserInputError/SystemError which propagate through
+ * createToolRunner's catch block to formatAppError.
+ */
+export declare function readGitHubIssueHandler(args: ReadIssueArgs, context: ToolContext): Promise<number>;
 export declare const tool: ToolDefinition;
+export {};

package/packages/tools/read-github-issue/dist/index.js

@@ -1,36 +1,6 @@
 import { execFile } from 'node:child_process';
+import { UserInputError, SystemError, createToolRunner } from '../../../tool-utils/dist/index.js';
 const ISSUE_FIELDS = 'number,title,body,state,author,labels,assignees,comments,createdAt,updatedAt,closedAt,url';
-function parseArgs(argv) {
-    const args = {
-        issue: null,
-        repo: null,
-        comments: false,
-        json: false,
-    };
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        switch (arg) {
-            case '--repo':
-                if (i + 1 < argv.length)
-                    args.repo = argv[++i];
-                break;
-            case '--comments':
-                args.comments = true;
-                break;
-            case '--json':
-                args.json = true;
-                break;
-            default:
-                if (!arg.startsWith('-')) {
-                    args.issue = arg;
-                }
-                break;
-        }
-        i++;
-    }
-    return args;
-}
 function runGh(cmdArgs) {
     return new Promise((resolve) => {
         execFile('gh', cmdArgs, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
@@ -100,26 +70,30 @@ function printSummary(issue, includeComments, context) {
         }
     }
 }
-export async function readGitHubIssueHandler(argv, context) {
+/**
+ * readGitHubIssueHandler — Wrapped in createToolRunner for schema-based
+ * argument parsing. The schema (see tool export) declares --repo, --json,
+ * --comments, and --help. Positional <issue> argument comes via positionals[0].
+ *
+ * Error handling uses UserInputError/SystemError which propagate through
+ * createToolRunner's catch block to formatAppError.
+ */
+export async function readGitHubIssueHandler(args, context) {
     const { stdout, stderr } = context;
-    const args = parseArgs(argv);
     if (!args.issue) {
-        stderr.write('Error: issue number or URL is required.\n');
-        return 1;
+        throw new UserInputError('Issue number or URL is required.');
     }
     const cmd = buildCommand(args);
     const result = await runGh(cmd);
     if (result.exitCode !== 0) {
-        stderr.write(result.stderr.trim() || 'gh issue view failed.\n');
-        return result.exitCode;
+        throw new SystemError(result.stderr.trim() || 'gh issue view failed');
     }
     let issue;
     try {
         issue = JSON.parse(result.stdout);
     }
     catch {
-        stderr.write('Error: unable to parse gh output as JSON.\n');
-        return 1;
+        throw new SystemError('Unable to parse gh output as JSON');
     }
     if (args.json) {
         stdout.write(JSON.stringify(issue, null, 2) + '\n');
@@ -133,5 +107,23 @@ export const tool = {
     name: 'read-github-issue',
     category: 'GitHub workflows',
     description: 'Read GitHub issue details through gh.',
-    handler: readGitHubIssueHandler,
+    handler: createToolRunner({
+        options: {
+            repo: { type: 'string' },
+            json: { type: 'boolean' },
+            comments: { type: 'boolean' },
+        },
+        allowPositionals: true,
+        usage: 'apltk read-github-issue [options] <issue>',
+        description: 'Read GitHub issue details through gh.',
+        handler: async (values, positionals, context) => {
+            const args = {
+                issue: positionals[0] ?? null,
+                repo: values.repo ?? null,
+                comments: values.comments === true,
+                json: values.json === true,
+            };
+            return readGitHubIssueHandler(args, context);
+        },
+    }),
 };