cadr-cli 1.10.0 → 2.0.1

package/src/commands/status.ts

@@ -0,0 +1,71 @@
+/**
+ * Status Command
+ * 
+ * Provides information about the current cADR configuration and environment.
+ */
+
+import { loadConfig, getDefaultConfigPath } from '../config';
+import { loggerInstance as logger } from '../logger';
+import { existsSync } from 'fs';
+
+/**
+ * Execute the status command
+ * Displays configuration and environment status
+ */
+export async function statusCommand(): Promise<void> {
+  try {
+    const configPath = getDefaultConfigPath();
+    const configExists = existsSync(configPath);
+
+    // eslint-disable-next-line no-console
+    console.log('\n🔍 cADR Status');
+    // eslint-disable-next-line no-console
+    console.log('='.repeat(30));
+
+    // Config Status
+    // eslint-disable-next-line no-console
+    console.log(`\n📄 Configuration:`);
+    if (configExists) {
+      // eslint-disable-next-line no-console
+      console.log(`   Path: ${configPath}`);
+      
+      const config = await loadConfig(configPath);
+      if (config) {
+        // eslint-disable-next-line no-console
+        console.log(`   Provider: ${config.provider}`);
+        // eslint-disable-next-line no-console
+        console.log(`   Model: ${config.analysis_model}`);
+        
+        // API Key Check
+        const apiKeySet = !!process.env[config.api_key_env];
+        // eslint-disable-next-line no-console
+        console.log(`   API Key (${config.api_key_env}): ${apiKeySet ? '✅ Set' : '❌ Not Set'}`);
+      } else {
+        // eslint-disable-next-line no-console
+        console.log('   ❌ Error loading configuration details.');
+      }
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(`   Path: ${configPath} (❌ Not Found)`);
+      // eslint-disable-next-line no-console
+      console.log('   Run `cadr init` to create one.');
+    }
+
+    // Git Status (Basic check)
+    // eslint-disable-next-line no-console
+    console.log(`\n🛠️ Environment:`);
+    // eslint-disable-next-line no-console
+    console.log(`   OS: ${process.platform}`);
+    // eslint-disable-next-line no-console
+    console.log(`   Node: ${process.version}`);
+    
+    // eslint-disable-next-line no-console
+    console.log('\nDone.\n');
+
+    logger.info('Status command completed');
+  } catch (error) {
+    logger.error('Status command failed', { error });
+    // eslint-disable-next-line no-console
+    console.error('\n❌ Failed to retrieve status. Check logs for details.\n');
+  }
+}

package/src/git/git.errors.ts

@@ -0,0 +1,10 @@
+export class GitError extends Error {
+  constructor(
+    message: string,
+    public readonly code: 'NOT_GIT_REPO' | 'GIT_NOT_FOUND' | 'GIT_ERROR',
+    public readonly originalError?: Error
+  ) {
+    super(message);
+    this.name = 'GitError';
+  }
+}

package/src/git/git.operations.ts

@@ -0,0 +1,85 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { GitError } from './git.errors';
+
+const execAsync = promisify(exec);
+
+export interface DiffOptions {
+  mode: 'staged' | 'all' | 'branch-diff';
+  base?: string;
+  head?: string;
+}
+
+function handleGitError(error: unknown, operation: string): never {
+  const errorWithCode = error as { code?: number };
+
+  if (errorWithCode.code === 128) {
+    throw new GitError(
+      `Not in a Git repository. Please run 'cadr' from within a Git repository.`,
+      'NOT_GIT_REPO',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+
+  if (errorWithCode.code === 127) {
+    throw new GitError(
+      'Git is not installed. Please install Git and try again.',
+      'GIT_NOT_FOUND',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+
+  throw new GitError(
+    `Unable to ${operation}. Please check repository permissions.`,
+    'GIT_ERROR',
+    error instanceof Error ? error : new Error(String(error))
+  );
+}
+
+async function execGitCommand(command: string): Promise<string> {
+  try {
+    const { stdout } = await execAsync(command);
+    return stdout;
+  } catch (error) {
+    handleGitError(error, command.split(' ')[1] || 'execute git command');
+  }
+}
+
+function parseFileList(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((file) => file.trim())
+    .filter((file) => file.length > 0);
+}
+
+export async function getStagedFiles(): Promise<string[]> {
+  const stdout = await execGitCommand('git diff --cached --name-only');
+  return parseFileList(stdout);
+}
+
+export async function getStagedDiff(): Promise<string> {
+  return execGitCommand('git diff --cached --unified=1');
+}
+
+export async function getAllChanges(): Promise<string[]> {
+  const stdout = await execGitCommand('git diff HEAD --name-only');
+  return parseFileList(stdout);
+}
+
+export async function getAllDiff(): Promise<string> {
+  return execGitCommand('git diff HEAD --unified=1');
+}
+
+export async function getChangedFiles(options: DiffOptions): Promise<string[]> {
+  if (options.mode === 'staged') {
+    return getStagedFiles();
+  }
+  return getAllChanges();
+}
+
+export async function getDiff(options: DiffOptions): Promise<string> {
+  if (options.mode === 'staged') {
+    return getStagedDiff();
+  }
+  return getAllDiff();
+}

package/src/git/index.ts

@@ -0,0 +1,3 @@
+export * from './git.errors';
+export * from './git.operations';
+export type { DiffOptions } from './git.operations';

package/src/index.ts

@@ -1,5 +1,6 @@
 import { initCommand } from './commands/init';
 import { analyzeCommand } from './commands/analyze';
+import { statusCommand } from './commands/status';
 
 // Version constants
 const CORE_VERSION = '0.0.1';
@@ -16,6 +17,7 @@ USAGE
 COMMANDS
   init              Create a cadr.yaml configuration file
   analyze           Analyze code changes and generate ADRs (default)
+  status            Show current configuration and environment status
   help              Show this help message
 
 ANALYZE OPTIONS
@@ -85,6 +87,10 @@ if (require.main === module) {
       case 'analyze':
         await analyzeCommand(args);
         break;
+
+      case 'status':
+        await statusCommand();
+        break;
         
       default:
         // Unknown command - show error and help

package/src/llm/index.ts

@@ -0,0 +1,2 @@
+export * from './llm';
+export * from './prompts';

package/src/{llm.ts → llm/llm.ts}

@@ -1,17 +1,7 @@
-/**
- * LLM Client Module
- *
- * Provider-based wrapper for analyzing code changes.
- * Implements fail-open error handling per constitution requirements.
- */
-
-import { getProvider } from './providers';
-import { AnalysisConfig } from './config';
-import { loggerInstance as logger } from './logger';
-
-/**
- * Analysis request data structure
- */
+import { getProvider } from '../providers';
+import { AnalysisConfig } from '../config';
+import { loggerInstance as logger } from '../logger';
+
 export interface AnalysisRequest {
   file_paths: string[];
   diff_content: string;
@@ -19,17 +9,6 @@ export interface AnalysisRequest {
   analysis_prompt: string;
 }
 
-/**
- * Rough token estimation (1 token ≈ 4 characters for English text)
- * This is a conservative estimate
- */
-function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-/**
- * Analysis result from LLM
- */
 export interface AnalysisResult {
   is_significant: boolean;
   reason: string;
@@ -37,27 +16,38 @@ export interface AnalysisResult {
   timestamp: string;
 }
 
-/**
- * Analysis response including potential errors
- */
 export interface AnalysisResponse {
   result: AnalysisResult | null;
   error?: string;
 }
 
-/**
- * Analyze staged changes using OpenAI LLM
- *
- * @param config - Analysis configuration with API settings
- * @param request - Analysis request with code changes
- * @returns Promise resolving to analysis response with result or error
- */
+export interface GenerationRequest {
+  file_paths: string[];
+  diff_content: string;
+  reason: string;
+  generation_prompt: string;
+}
+
+export interface GenerationResult {
+  content: string;
+  title: string;
+  timestamp: string;
+}
+
+export interface GenerationResponse {
+  result: GenerationResult | null;
+  error?: string;
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
 export async function analyzeChanges(
   config: AnalysisConfig,
   request: AnalysisRequest
 ): Promise<AnalysisResponse> {
   try {
-    // Check if API key is available
     const apiKey = process.env[config.api_key_env];
     if (!apiKey) {
       logger.warn('API key not found in environment', {
@@ -65,21 +55,19 @@ export async function analyzeChanges(
       });
       return {
         result: null,
-        error: `API key not found: ${config.api_key_env} environment variable is not set`
+        error: `API key not found: ${config.api_key_env} environment variable is not set`,
       };
     }
 
-    // Estimate tokens for logging and validation
     const estimatedTokens = estimateTokens(request.analysis_prompt);
-    
+
     logger.info('Sending analysis request to LLM', {
       provider: config.provider,
       model: config.analysis_model,
       file_count: request.file_paths.length,
       estimated_tokens: estimatedTokens,
     });
-    
-    // Warn if token estimate is high (most models have 8k-32k limits)
+
     if (estimatedTokens > 7000) {
       logger.warn('High token count detected', {
         estimated_tokens: estimatedTokens,
@@ -99,28 +87,24 @@ export async function analyzeChanges(
       logger.warn('No response content from LLM', { provider: config.provider });
       return {
         result: null,
-        error: 'No response content from LLM'
+        error: 'No response content from LLM',
       };
     }
 
-    // Parse JSON response - handle markdown-wrapped JSON
     let parsedResponse: { is_significant: boolean; reason: string; confidence?: number };
     try {
-      // Try to extract JSON from markdown code blocks if present
       let jsonContent = responseContent.trim();
-      
-      // Remove markdown code block if present: ```json ... ``` or ``` ... ```
+
       const codeBlockMatch = jsonContent.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
       if (codeBlockMatch) {
         jsonContent = codeBlockMatch[1].trim();
       }
-      
-      // Try to find JSON object if there's surrounding text
+
       const jsonMatch = jsonContent.match(/\{[\s\S]*\}/);
       if (jsonMatch) {
         jsonContent = jsonMatch[0];
       }
-      
+
       parsedResponse = JSON.parse(jsonContent);
     } catch (parseError) {
       logger.warn('Failed to parse LLM response as JSON', {
@@ -129,11 +113,10 @@ export async function analyzeChanges(
       });
       return {
         result: null,
-        error: `Failed to parse LLM response as JSON. Response was:\n${responseContent.substring(0, 200)}...`
+        error: `Failed to parse LLM response as JSON. Response was:\n${responseContent.substring(0, 200)}...`,
       };
     }
 
-    // Validate response format
     if (
       typeof parsedResponse.is_significant !== 'boolean' ||
       typeof parsedResponse.reason !== 'string'
@@ -143,29 +126,26 @@ export async function analyzeChanges(
       });
       return {
         result: null,
-        error: `Invalid response format from LLM. Expected {is_significant: boolean, reason: string}, got: ${JSON.stringify(parsedResponse).substring(0, 150)}...`
+        error: `Invalid response format from LLM. Expected {is_significant: boolean, reason: string}, got: ${JSON.stringify(parsedResponse).substring(0, 150)}...`,
       };
     }
-    
-    // Reason is required when is_significant is true, but can be empty when false
+
     if (parsedResponse.is_significant && !parsedResponse.reason) {
       logger.warn('Missing reason for significant change', {
         response: parsedResponse,
       });
       return {
         result: null,
-        error: 'LLM indicated significant change but provided no reason'
+        error: 'LLM indicated significant change but provided no reason',
       };
     }
 
-    // Build result with timestamp
     const result: AnalysisResult = {
       is_significant: parsedResponse.is_significant,
       reason: parsedResponse.reason,
       timestamp: new Date().toISOString(),
     };
 
-    // Include confidence if provided
     if (
       typeof parsedResponse.confidence === 'number' &&
       parsedResponse.confidence >= 0 &&
@@ -181,22 +161,20 @@ export async function analyzeChanges(
 
     return { result, error: undefined };
   } catch (error) {
-    // Fail-open: log error and return descriptive error message
     const errorObj = error as { status?: number; code?: string; message?: string };
     let errorMessage: string;
 
-    // Check for specific error types and provide helpful messages
     if (errorObj.status === 401) {
       errorMessage = 'Invalid API key - please check your API key configuration';
       logger.warn('LLM API authentication failed', { error: errorObj });
     } else if (errorObj.status === 400 && errorObj.message?.includes('maximum context length')) {
-      // Extract token counts from error message if available
       const tokenMatch = errorObj.message.match(/(\d+)\s+tokens/g);
-      errorMessage = 'Diff too large for model context window. Try:\n' +
+      errorMessage =
+        'Diff too large for model context window. Try:\n' +
         '  • Stage fewer files at once\n' +
         '  • Use a model with larger context window in cadr.yaml\n' +
         '  • Add ignore patterns to filter large files';
-      logger.warn('LLM context length exceeded', { 
+      logger.warn('LLM context length exceeded', {
         error: errorObj,
         tokens: tokenMatch,
       });
@@ -218,46 +196,11 @@ export async function analyzeChanges(
   }
 }
 
-/**
- * Generation request data structure
- */
-export interface GenerationRequest {
-  file_paths: string[];
-  diff_content: string;
-  reason: string;
-  generation_prompt: string;
-}
-
-/**
- * Generation result from LLM
- */
-export interface GenerationResult {
-  content: string;
-  title: string;
-  timestamp: string;
-}
-
-/**
- * Generation response including potential errors
- */
-export interface GenerationResponse {
-  result: GenerationResult | null;
-  error?: string;
-}
-
-/**
- * Generate ADR content using LLM
- *
- * @param config - Analysis configuration with API settings
- * @param request - Generation request with code changes
- * @returns Promise resolving to generation response with result or error
- */
 export async function generateADRContent(
   config: AnalysisConfig,
   request: GenerationRequest
 ): Promise<GenerationResponse> {
   try {
-    // Check if API key is available
     const apiKey = process.env[config.api_key_env];
     if (!apiKey) {
       logger.warn('API key not found in environment for generation', {
@@ -265,7 +208,7 @@ export async function generateADRContent(
       });
       return {
         result: null,
-        error: `API key not found: ${config.api_key_env} environment variable is not set`
+        error: `API key not found: ${config.api_key_env} environment variable is not set`,
       };
     }
 
@@ -278,30 +221,27 @@ export async function generateADRContent(
     const provider = getProvider(config.provider);
     const responseContent = await provider.analyze(request.generation_prompt, {
       apiKey,
-      model: config.analysis_model, // Using same model per user request
+      model: config.analysis_model,
       timeoutMs: config.timeout_seconds * 1000,
     });
 
     if (!responseContent) {
-      logger.warn('No response content from LLM for generation', { 
-        provider: config.provider 
+      logger.warn('No response content from LLM for generation', {
+        provider: config.provider,
       });
       return {
         result: null,
-        error: 'No response content from LLM'
+        error: 'No response content from LLM',
       };
     }
 
-    // Clean up the response - remove markdown code fences if LLM added them
     let cleanedContent = responseContent.trim();
-    
-    // Remove markdown code block if present
+
     const codeBlockMatch = cleanedContent.match(/```(?:markdown|md)?\s*\n?([\s\S]*?)\n?```/);
     if (codeBlockMatch) {
       cleanedContent = codeBlockMatch[1].trim();
     }
 
-    // Extract title from first line (should be # Title)
     const titleMatch = cleanedContent.match(/^#\s+(.+)$/m);
     const title = titleMatch ? titleMatch[1].trim() : 'Untitled Decision';
 
@@ -318,7 +258,6 @@ export async function generateADRContent(
 
     return { result, error: undefined };
   } catch (error) {
-    // Fail-open: log error and return descriptive error message
     const errorObj = error as { status?: number; code?: string; message?: string };
     let errorMessage: string;
 

package/src/{prompts.ts → llm/prompts.ts}

@@ -1,18 +1,5 @@
-/**
- * Prompts Module
- * 
- * Contains versioned prompt templates for LLM analysis and ADR generation.
- * Follows the constitution requirement for versioned prompts.
- */
-
 import * as readline from 'readline';
 
-/**
- * Version 1 of the analysis prompt template.
- * 
- * This prompt is designed to analyze code changes for architectural significance.
- * It uses specific criteria for determining significance and enforces strict JSON output.
- */
 export const ANALYSIS_PROMPT_V1 = `
 You are an expert principal engineer and software architect acting as a meticulous code reviewer. Your sole task is to determine if the provided git diff represents an architecturally significant change that warrants an Architectural Decision Record (ADR).
 
@@ -35,34 +22,6 @@ Respond ONLY with a single, minified JSON object with no preamble, no markdown,
 The "reason" should be a concise, one-sentence explanation for your decision, suitable for showing to a developer. If the change is not significant, the reason should be an empty string.
 `;
 
-/**
- * Formats a prompt template by replacing placeholders with actual data.
- * 
- * @param template - The prompt template with placeholders
- * @param data - Object containing file_paths and diff_content
- * @returns Formatted prompt with placeholders replaced
- */
-export function formatPrompt(
-  template: string, 
-  data: { file_paths: string[], diff_content: string }
-): string {
-  // Format file paths as a readable list
-  const formattedFilePaths = data.file_paths.length > 0 
-    ? data.file_paths.join('\n')
-    : 'No files';
-
-  // Replace placeholders with actual data
-  return template
-    .replace('{file_paths}', formattedFilePaths)
-    .replace('{diff_content}', data.diff_content);
-}
-
-/**
- * Version 1 of the generation prompt template.
- * 
- * This prompt generates ADRs following the MADR (Markdown Architectural Decision Records) format.
- * MADR is a lean template for documenting architectural decisions in a structured way.
- */
 export const GENERATION_PROMPT_V1 = `
 You are an expert software architect. Your task is to write a comprehensive Architectural Decision Record (ADR) following the MADR (Markdown Architectural Decision Records) template.
 
@@ -123,33 +82,30 @@ IMPORTANT INSTRUCTIONS:
 Respond ONLY with the markdown content of the ADR. Do not include any preamble, explanation, or markdown code fences. Start directly with the # title.
 `;
 
-/**
- * Formats the generation prompt with actual diff data
- * 
- * @param data - Object containing file_paths and diff_content
- * @returns Formatted generation prompt
- */
-export function formatGenerationPrompt(
-  data: { file_paths: string[], diff_content: string }
+export function formatPrompt(
+  template: string,
+  data: { file_paths: string[]; diff_content: string }
 ): string {
-  const formattedFilePaths = data.file_paths.length > 0 
-    ? data.file_paths.join('\n')
-    : 'No files';
+  const formattedFilePaths = data.file_paths.length > 0 ? data.file_paths.join('\n') : 'No files';
+
+  return template
+    .replace('{file_paths}', formattedFilePaths)
+    .replace('{diff_content}', data.diff_content);
+}
+
+export function formatGenerationPrompt(data: {
+  file_paths: string[];
+  diff_content: string;
+}): string {
+  const formattedFilePaths = data.file_paths.length > 0 ? data.file_paths.join('\n') : 'No files';
 
   const currentDate = new Date().toISOString().split('T')[0];
 
-  return GENERATION_PROMPT_V1
-    .replace('{file_paths}', formattedFilePaths)
+  return GENERATION_PROMPT_V1.replace('{file_paths}', formattedFilePaths)
     .replace('{diff_content}', data.diff_content)
     .replace('{current_date}', currentDate);
 }
 
-/**
- * Prompt user for ADR generation confirmation
- * 
- * @param reason - The reason why this change is architecturally significant
- * @returns Promise<boolean> - true if user wants to generate, false otherwise
- */
 export async function promptForGeneration(reason: string): Promise<boolean> {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -157,18 +113,20 @@ export async function promptForGeneration(reason: string): Promise<boolean> {
       output: process.stdout,
     });
 
-    // eslint-disable-next-line no-console
+    /* eslint-disable-next-line no-console */
     console.log(`\n💭 ${reason}\n`);
-    
-    rl.question('📝 Would you like to generate an ADR for this change? (Press ENTER or type "yes" to confirm, "no" to skip): ', (answer) => {
-      rl.close();
-      
-      const normalized = answer.trim().toLowerCase();
-      
-      // Accept: empty (ENTER), "y", "yes"
-      const confirmed = normalized === '' || normalized === 'y' || normalized === 'yes';
-      
-      resolve(confirmed);
-    });
+
+    rl.question(
+      '📝 Would you like to generate an ADR for this change? (Press ENTER or type "yes" to confirm, "no" to skip): ',
+      (answer) => {
+        rl.close();
+
+        const normalized = answer.trim().toLowerCase();
+
+        const confirmed = normalized === '' || normalized === 'y' || normalized === 'yes';
+
+        resolve(confirmed);
+      }
+    );
   });
 }