feat: Implement GitHub issue validation endpoint and UI integration

- Added a new endpoint for validating GitHub issues using the Claude SDK.
- Introduced validation schema and logic to handle issue validation requests.
- Updated GitHub routes to include the new validation route.
- Enhanced the UI with a validation dialog and button to trigger issue validation.
- Mapped issue complexity to feature priority for better task management.
- Integrated validation results display in the UI, allowing users to convert validated issues into tasks.

apps/server/src/routes/github/index.ts

@@ -3,16 +3,19 @@
  */
 
 import { Router } from 'express';
+import { validatePathParams } from '../../middleware/validate-paths.js';
 import { createCheckGitHubRemoteHandler } from './routes/check-github-remote.js';
 import { createListIssuesHandler } from './routes/list-issues.js';
 import { createListPRsHandler } from './routes/list-prs.js';
+import { createValidateIssueHandler } from './routes/validate-issue.js';
 
 export function createGitHubRoutes(): Router {
   const router = Router();
 
-  router.post('/check-remote', createCheckGitHubRemoteHandler());
-  router.post('/issues', createListIssuesHandler());
-  router.post('/prs', createListPRsHandler());
+  router.post('/check-remote', validatePathParams('projectPath'), createCheckGitHubRemoteHandler());
+  router.post('/issues', validatePathParams('projectPath'), createListIssuesHandler());
+  router.post('/prs', validatePathParams('projectPath'), createListPRsHandler());
+  router.post('/validate-issue', validatePathParams('projectPath'), createValidateIssueHandler());
 
   return router;
 }

apps/server/src/routes/github/routes/validate-issue.ts

@@ -0,0 +1,164 @@
+/**
+ * POST /validate-issue endpoint - Validate a GitHub issue using Claude SDK
+ *
+ * Scans the codebase to determine if an issue is valid, invalid, or needs clarification.
+ */
+
+import type { Request, Response } from 'express';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { createLogger } from '@automaker/utils';
+import type { IssueValidationResult } from '@automaker/types';
+import { createSuggestionsOptions } from '../../../lib/sdk-options.js';
+import {
+  issueValidationSchema,
+  ISSUE_VALIDATION_SYSTEM_PROMPT,
+  buildValidationPrompt,
+} from './validation-schema.js';
+import { getErrorMessage, logError } from './common.js';
+
+const logger = createLogger('IssueValidation');
+
+/**
+ * Request body for issue validation
+ */
+interface ValidateIssueRequestBody {
+  projectPath: string;
+  issueNumber: number;
+  issueTitle: string;
+  issueBody: string;
+  issueLabels?: string[];
+}
+
+/**
+ * Creates the handler for validating GitHub issues against the codebase.
+ *
+ * Uses Claude SDK with:
+ * - Read-only tools (Read, Glob, Grep) for codebase analysis
+ * - JSON schema structured output for reliable parsing
+ * - System prompt guiding the validation process
+ */
+export function createValidateIssueHandler() {
+  return async (req: Request, res: Response): Promise<void> => {
+    // Declare timeoutId outside try block for proper cleanup
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      const { projectPath, issueNumber, issueTitle, issueBody, issueLabels } =
+        req.body as ValidateIssueRequestBody;
+
+      // Validate required fields
+      if (!projectPath) {
+        res.status(400).json({ success: false, error: 'projectPath is required' });
+        return;
+      }
+
+      if (!issueNumber || typeof issueNumber !== 'number') {
+        res
+          .status(400)
+          .json({ success: false, error: 'issueNumber is required and must be a number' });
+        return;
+      }
+
+      if (!issueTitle || typeof issueTitle !== 'string') {
+        res.status(400).json({ success: false, error: 'issueTitle is required' });
+        return;
+      }
+
+      if (typeof issueBody !== 'string') {
+        res.status(400).json({ success: false, error: 'issueBody must be a string' });
+        return;
+      }
+
+      logger.info(`Validating issue #${issueNumber}: ${issueTitle}`);
+
+      // Build the prompt
+      const prompt = buildValidationPrompt(issueNumber, issueTitle, issueBody, issueLabels);
+
+      // Create abort controller with 2 minute timeout for validation
+      const abortController = new AbortController();
+      const VALIDATION_TIMEOUT_MS = 120000; // 2 minutes
+      timeoutId = setTimeout(() => {
+        logger.warn(`Validation timeout reached after ${VALIDATION_TIMEOUT_MS}ms`);
+        abortController.abort();
+      }, VALIDATION_TIMEOUT_MS);
+
+      // Create SDK options with structured output and abort controller
+      const options = createSuggestionsOptions({
+        cwd: projectPath,
+        systemPrompt: ISSUE_VALIDATION_SYSTEM_PROMPT,
+        abortController,
+        outputFormat: {
+          type: 'json_schema',
+          schema: issueValidationSchema as Record<string, unknown>,
+        },
+      });
+
+      // Execute the query
+      const stream = query({ prompt, options });
+      let validationResult: IssueValidationResult | null = null;
+      let responseText = '';
+
+      for await (const msg of stream) {
+        // Collect assistant text for debugging/fallback
+        if (msg.type === 'assistant' && msg.message?.content) {
+          for (const block of msg.message.content) {
+            if (block.type === 'text') {
+              responseText += block.text;
+            }
+          }
+        }
+
+        // Extract structured output on success
+        if (msg.type === 'result' && msg.subtype === 'success') {
+          const resultMsg = msg as { structured_output?: IssueValidationResult };
+          if (resultMsg.structured_output) {
+            validationResult = resultMsg.structured_output;
+            logger.debug('Received structured output:', validationResult);
+          }
+        }
+
+        // Handle errors
+        if (msg.type === 'result') {
+          const resultMsg = msg as { subtype?: string };
+          if (resultMsg.subtype === 'error_max_structured_output_retries') {
+            logger.error('Failed to produce valid structured output after retries');
+            throw new Error('Could not produce valid validation output');
+          }
+        }
+      }
+
+      // Require structured output - no fragile fallback parsing
+      if (!validationResult) {
+        logger.error('No structured output received from Claude SDK');
+        logger.debug('Raw response text:', responseText);
+        throw new Error('Validation failed: no structured output received');
+      }
+
+      // Clear the timeout since we completed successfully
+      clearTimeout(timeoutId);
+
+      logger.info(`Issue #${issueNumber} validation complete: ${validationResult.verdict}`);
+      res.json({
+        success: true,
+        issueNumber,
+        validation: validationResult,
+      });
+    } catch (error) {
+      // Clear timeout on error as well (if it was set)
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      logError(error, `Issue validation failed`);
+      logger.error('Issue validation error:', error);
+
+      // Check if response already sent
+      if (!res.headersSent) {
+        res.status(500).json({
+          success: false,
+          error: getErrorMessage(error),
+        });
+      }
+    }
+  };
+}

apps/server/src/routes/github/routes/validation-schema.ts

@@ -0,0 +1,138 @@
+/**
+ * Issue Validation Schema and System Prompt
+ *
+ * Defines the JSON schema for Claude's structured output and
+ * the system prompt that guides the validation process.
+ */
+
+/**
+ * JSON Schema for issue validation structured output.
+ * Used with Claude SDK's outputFormat option to ensure reliable parsing.
+ */
+export const issueValidationSchema = {
+  type: 'object',
+  properties: {
+    verdict: {
+      type: 'string',
+      enum: ['valid', 'invalid', 'needs_clarification'],
+      description: 'The validation verdict for the issue',
+    },
+    confidence: {
+      type: 'string',
+      enum: ['high', 'medium', 'low'],
+      description: 'How confident the AI is in its assessment',
+    },
+    reasoning: {
+      type: 'string',
+      description: 'Detailed explanation of the verdict',
+    },
+    bugConfirmed: {
+      type: 'boolean',
+      description: 'For bug reports: whether the bug was confirmed in the codebase',
+    },
+    relatedFiles: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Files related to the issue found during analysis',
+    },
+    suggestedFix: {
+      type: 'string',
+      description: 'Suggested approach to fix or implement the issue',
+    },
+    missingInfo: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Information needed when verdict is needs_clarification',
+    },
+    estimatedComplexity: {
+      type: 'string',
+      enum: ['trivial', 'simple', 'moderate', 'complex', 'very_complex'],
+      description: 'Estimated effort to address the issue',
+    },
+  },
+  required: ['verdict', 'confidence', 'reasoning'],
+  additionalProperties: false,
+} as const;
+
+/**
+ * System prompt that guides Claude in validating GitHub issues.
+ * Instructs the model to use read-only tools to analyze the codebase.
+ */
+export const ISSUE_VALIDATION_SYSTEM_PROMPT = `You are an expert code analyst validating GitHub issues against a codebase.
+
+Your task is to analyze a GitHub issue and determine if it's valid by scanning the codebase.
+
+## Validation Process
+
+1. **Read the issue carefully** - Understand what is being reported or requested
+2. **Search the codebase** - Use Glob to find relevant files by pattern, Grep to search for keywords
+3. **Examine the code** - Use Read to look at the actual implementation in relevant files
+4. **Form your verdict** - Based on your analysis, determine if the issue is valid
+
+## Verdicts
+
+- **valid**: The issue describes a real problem that exists in the codebase, or a clear feature request that can be implemented. The referenced files/components exist and the issue is actionable.
+
+- **invalid**: The issue describes behavior that doesn't exist, references non-existent files or components, is based on a misunderstanding of the code, or the described "bug" is actually expected behavior.
+
+- **needs_clarification**: The issue lacks sufficient detail to verify. Specify what additional information is needed in the missingInfo field.
+
+## For Bug Reports, Check:
+- Do the referenced files/components exist?
+- Does the code match what the issue describes?
+- Is the described behavior actually a bug or expected?
+- Can you locate the code that would cause the reported issue?
+
+## For Feature Requests, Check:
+- Does the feature already exist?
+- Is the implementation location clear?
+- Is the request technically feasible given the codebase structure?
+
+## Response Guidelines
+
+- **Always include relatedFiles** when you find relevant code
+- **Set bugConfirmed to true** only if you can definitively confirm a bug exists in the code
+- **Provide a suggestedFix** when you have a clear idea of how to address the issue
+- **Use missingInfo** when the verdict is needs_clarification to list what's needed
+- **Set estimatedComplexity** to help prioritize:
+  - trivial: Simple text changes, one-line fixes
+  - simple: Small changes to one file
+  - moderate: Changes to multiple files or moderate logic changes
+  - complex: Significant refactoring or new feature implementation
+  - very_complex: Major architectural changes or cross-cutting concerns
+
+Be thorough in your analysis but focus on files that are directly relevant to the issue.`;
+
+/**
+ * Build the user prompt for issue validation.
+ *
+ * Creates a structured prompt that includes the issue details for Claude
+ * to analyze against the codebase.
+ *
+ * @param issueNumber - The GitHub issue number
+ * @param issueTitle - The issue title
+ * @param issueBody - The issue body/description
+ * @param issueLabels - Optional array of label names
+ * @returns Formatted prompt string for the validation request
+ */
+export function buildValidationPrompt(
+  issueNumber: number,
+  issueTitle: string,
+  issueBody: string,
+  issueLabels?: string[]
+): string {
+  const labelsSection = issueLabels?.length ? `\n\n**Labels:** ${issueLabels.join(', ')}` : '';
+
+  return `Please validate the following GitHub issue by analyzing the codebase:
+
+## Issue #${issueNumber}: ${issueTitle}
+${labelsSection}
+
+### Description
+
+${issueBody || '(No description provided)'}
+
+---
+
+Scan the codebase to verify this issue. Look for the files, components, or functionality mentioned. Determine if this issue is valid, invalid, or needs clarification.`;
+}