aiwf/docs/API_REFERENCE_FULL.md

AI Workflow Framework for Claude Code with multi-language support (Korean/English)

# AIWF Complete API Reference

[한국어로 보기](API_REFERENCE_FULL.ko.md)

## Table of Contents

1. [Core APIs](#core-apis)
   - [Resource Loader](#resource-loader)
   - [State Management](#state-management)
   - [Template System](#template-system)
2. [Command APIs](#command-apis)
   - [AI Tool Command](#ai-tool-command)
   - [Compress Command](#compress-command)
   - [Create Project](#create-project)
   - [Evaluate Command](#evaluate-command)
   - [Feature Command](#feature-command)
   - [Persona Command](#persona-command)
   - [State Command](#state-command)
   - [Token Command](#token-command)
   - [YOLO Config](#yolo-config)
3. [Utility APIs](#utility-apis)
   - [Checkpoint Manager](#checkpoint-manager)
   - [Git Utilities](#git-utilities)
   - [Token Counter](#token-counter)
   - [Text Processors](#text-processors)
4. [Plugin APIs](#plugin-apis)
   - [Plugin Interface](#plugin-interface)
   - [Hook System](#hook-system)
5. [AI Integration APIs](#ai-integration-apis)
   - [Persona Manager](#persona-manager)
   - [Compression Engine](#compression-engine)
   - [Evaluation System](#evaluation-system)

---

## Core APIs

### Resource Loader

The Resource Loader manages all framework resources, providing a unified interface for accessing bundled and user resources.

#### Class: `ResourceLoader`

```javascript
import { ResourceLoader } from 'aiwf/lib/resource-loader';
```

##### Constructor

```javascript
new ResourceLoader(options?: ResourceLoaderOptions)
```

**Options:**
```typescript
interface ResourceLoaderOptions {
  bundledPath?: string;      // Path to bundled resources
  userPath?: string;         // Path to user resources
  preferUserResources?: boolean; // Prefer user over bundled (default: true)
}
```

##### Methods

###### `resolvePath(resourceType, resourceName)`

Resolves the path to a resource, checking user directory first, then bundled resources.

```javascript
async resolvePath(resourceType: string, resourceName: string): Promise<string>
```

**Example:**
```javascript
const loader = new ResourceLoader();
const personaPath = await loader.resolvePath('personas', 'analyst.json');
```

###### `loadResource(resourceType, resourceName)`

Loads and parses a resource file.

```javascript
async loadResource(resourceType: string, resourceName: string): Promise<any>
```

**Supported formats:**
- JSON (`.json`)
- YAML (`.yaml`, `.yml`)
- JavaScript modules (`.js`)
- Markdown (`.md`)

###### `listResources(resourceType)`

Lists all available resources of a given type.

```javascript
async listResources(resourceType: string): Promise<string[]>
```

###### `copyResource(resourceType, resourceName, destination)`

Copies a resource to a specified location.

```javascript
async copyResource(
  resourceType: string, 
  resourceName: string, 
  destination: string
): Promise<void>
```

### State Management

Manages application and project state with support for checkpoints and atomic updates.

#### Class: `StateIndexManager`

```javascript
import { StateIndexManager } from 'aiwf/lib/state/state-index';
```

##### Constructor

```javascript
new StateIndexManager(aiwfPath: string)
```

##### Methods

###### `loadState()`

Loads the current state from disk.

```javascript
async loadState(): Promise<StateIndex>
```

**Returns:**
```typescript
interface StateIndex {
  version: string;
  last_updated: string;
  last_updated_by: string;
  project_info: ProjectInfo;
  milestones: Milestone[];
  sprints: Sprint[];
  tasks: Task[];
  workflow_mode: WorkflowMode;
}
```

###### `saveState(state)`

Saves state to disk with automatic backup.

```javascript
async saveState(state: StateIndex): Promise<void>
```

###### `updateProjectInfo(updates)`

Updates project information.

```javascript
async updateProjectInfo(updates: Partial<ProjectInfo>): Promise<void>
```

###### `addMilestone(milestone)`

Adds a new milestone to the project.

```javascript
async addMilestone(milestone: Milestone): Promise<void>
```

### Template System

Manages project templates and code generation.

#### Class: `TemplateEngine`

```javascript
import { TemplateEngine } from 'aiwf/lib/template-engine';
```

##### Methods

###### `listTemplates()`

Lists all available project templates.

```javascript
async listTemplates(): Promise<TemplateInfo[]>
```

###### `createFromTemplate(templateName, targetPath, variables)`

Creates a new project from a template.

```javascript
async createFromTemplate(
  templateName: string,
  targetPath: string,
  variables: Record<string, string>
): Promise<void>
```

**Example:**
```javascript
const engine = new TemplateEngine();
await engine.createFromTemplate('api-server', './my-api', {
  projectName: 'My API',
  author: 'John Doe',
  description: 'My awesome API server'
});
```

---

## Command APIs

### AI Tool Command

Manages AI tool integrations and configurations.

#### Class: `AIToolCommand`

```javascript
import AIToolCommand from 'aiwf/commands/ai-tool';
```

##### Methods

###### `execute(args)`

Executes AI tool commands.

```javascript
async execute(args: string[]): Promise<void>
```

**Subcommands:**
- `list` - List all available AI tools
- `activate <tool>` - Activate an AI tool
- `configure <tool>` - Configure an AI tool
- `status` - Show current AI tool status

### Compress Command

Provides various compression strategies for optimizing context.

#### Functions

###### `compress(mode, content, options)`

Compresses content using specified strategy.

```javascript
async compress(
  mode: CompressionMode,
  content: string,
  options?: CompressionOptions
): Promise<string>
```

**Compression Modes:**
- `simple` - Basic whitespace and comment removal
- `moderate` - Balanced compression
- `aggressive` - Maximum compression
- `custom` - User-defined rules

**Options:**
```typescript
interface CompressionOptions {
  preserveComments?: boolean;
  preserveWhitespace?: boolean;
  maxLineLength?: number;
  customRules?: CompressionRule[];
}
```

### Create Project

Creates new AIWF projects from templates.

#### Function: `createProject`

```javascript
async createProject(options: CreateProjectOptions): Promise<void>
```

**Options:**
```typescript
interface CreateProjectOptions {
  template: string;
  name: string;
  path?: string;
  variables?: Record<string, string>;
  skipInstall?: boolean;
  gitInit?: boolean;
}
```

### Evaluate Command

Evaluates AI responses and code quality.

#### Class: `EvaluateCommand`

##### Methods

###### `evaluateResponse(file, options)`

Evaluates the quality of an AI response.

```javascript
async evaluateResponse(
  file: string, 
  options?: EvaluationOptions
): Promise<EvaluationResult>
```

###### `evaluateCode(file, options)`

Evaluates code quality and best practices.

```javascript
async evaluateCode(
  file: string,
  options?: CodeEvaluationOptions
): Promise<CodeEvaluationResult>
```

### Feature Command

Manages feature tracking and development workflow.

#### Functions

###### `createFeature(name, description)`

Creates a new feature entry.

```javascript
async createFeature(
  name: string, 
  description?: string
): Promise<FeatureEntry>
```

###### `updateFeatureStatus(id, status)`

Updates the status of a feature.

```javascript
async updateFeatureStatus(
  id: string,
  status: FeatureStatus
): Promise<void>
```

**Feature Statuses:**
- `planned`
- `in-progress`
- `testing`
- `completed`
- `deployed`

### Persona Command

Manages AI personas and their configurations.

#### Class: `PersonaCommand`

##### Methods

###### `listPersonas()`

Lists all available personas.

```javascript
async listPersonas(): Promise<PersonaInfo[]>
```

###### `activatePersona(name)`

Activates a specific persona.

```javascript
async activatePersona(name: string): Promise<void>
```

###### `createPersona(name, config)`

Creates a custom persona.

```javascript
async createPersona(
  name: string,
  config: PersonaConfig
): Promise<void>
```

### State Command

Manages project state and workflow transitions.

#### Class: `StateCommand`

##### Methods

###### `showStatus()`

Displays current project state.

```javascript
async showStatus(): Promise<StateStatus>
```

###### `checkpoint(name, description)`

Creates a state checkpoint.

```javascript
async checkpoint(
  name: string,
  description?: string
): Promise<CheckpointInfo>
```

###### `restore(checkpointId)`

Restores from a checkpoint.

```javascript
async restore(checkpointId: string): Promise<void>
```

### Token Command

Monitors and manages AI token usage.

#### Functions

###### `trackUsage(input, output, model)`

Records token usage.

```javascript
async trackUsage(
  input: string,
  output: string,
  model?: string
): Promise<UsageRecord>
```

###### `getUsageReport(period)`

Generates usage report.

```javascript
async getUsageReport(
  period?: 'day' | 'week' | 'month'
): Promise<UsageReport>
```

### YOLO Config

Manages YOLO mode configuration.

#### Functions

###### `createYoloConfig(options)`

Creates YOLO configuration file.

```javascript
async createYoloConfig(options?: YoloOptions): Promise<void>
```

###### `createInteractiveYoloConfig()`

Creates configuration through interactive prompts.

```javascript
async createInteractiveYoloConfig(): Promise<void>
```

---

## Utility APIs

### Engineering Guard

Prevents over-engineering and maintains code quality during autonomous execution.

#### Class: `EngineeringGuard`

```javascript
import { EngineeringGuard } from 'aiwf/utils/engineering-guard';
```

##### Constructor

```javascript
new EngineeringGuard(configPath?: string)
```

##### Methods

###### `checkFileComplexity(filePath)`

Checks a single file for complexity violations.

```javascript
async checkFileComplexity(filePath: string): Promise<void>
```

###### `checkProject(projectPath, filePatterns)`

Performs comprehensive project-wide complexity analysis.

```javascript
async checkProject(
  projectPath: string,
  filePatterns?: string[]
): Promise<GuardReport>
```

**Returns:**
```typescript
interface GuardReport {
  passed: boolean;
  violations: Violation[];
  warnings: Warning[];
  summary: {
    total_violations: number;
    high_severity: number;
    medium_severity: number;
    warnings: number;
  };
  recommendations: string[];
}
```

###### `provideFeedback(filePath, content)`

Provides real-time feedback during development.

```javascript
async provideFeedback(
  filePath: string,
  content?: string
): Promise<Feedback[]>
```

###### `generateReport()`

Generates comprehensive analysis report.

```javascript
generateReport(): GuardReport
```

### Checkpoint Manager

Manages state checkpoints and recovery.

#### Class: `CheckpointManager`

```javascript
import { CheckpointManager } from 'aiwf/utils/checkpoint-manager';
```

##### Constructor

```javascript
new CheckpointManager(projectRoot: string)
```

##### Methods

###### `startSession(sprintId, mode)`

Starts a new YOLO session with tracking.

```javascript
async startSession(sprintId: string, mode?: string): Promise<void>
```

###### `startTask(taskId, taskInfo)`

Begins tracking a specific task.

```javascript
async startTask(taskId: string, taskInfo?: any): Promise<void>
```

###### `completeTask(taskId, result)`

Marks a task as completed with results.

```javascript
async completeTask(taskId: string, result?: any): Promise<void>
```

###### `createCheckpoint(type, metadata)`

Creates a new checkpoint.

```javascript
async createCheckpoint(
  type?: string,
  metadata?: CheckpointMetadata
): Promise<string>
```

###### `listCheckpoints()`

Lists all available checkpoints.

```javascript
async listCheckpoints(): Promise<CheckpointInfo[]>
```

###### `restoreFromCheckpoint(checkpointId)`

Restores from a specific checkpoint.

```javascript
async restoreFromCheckpoint(checkpointId: string): Promise<RestoreResult>
```

**Returns:**
```typescript
interface RestoreResult {
  success: boolean;
  checkpoint: Checkpoint;
  tasks_to_resume: {
    completed: string[];
    current: string | null;
    next_task_hint: string;
  };
}
```

###### `generateProgressReport()`

Generates comprehensive progress report.

```javascript
async generateProgressReport(): Promise<ProgressReport>
```

**Returns:**
```typescript
interface ProgressReport {
  session: {
    id: string;
    started: string;
    sprint: string;
    mode: string;
  };
  progress: {
    completed: number;
    failed: number;
    skipped: number;
    current: string;
  };
  performance: {
    total_time: string;
    avg_task_time: string;
    success_rate: string;
  };
  checkpoints: CheckpointInfo[];
  recommendations: string[];
}
```

###### `endSession(summary)`

Ends the current session and generates final report.

```javascript
async endSession(summary?: any): Promise<ProgressReport>
```

### Git Utilities

Provides Git integration utilities.

#### Functions

###### `parseCommitMessage(message)`

Parses structured commit messages.

```javascript
parseCommitMessage(message: string): ParsedCommit
```

**Returns:**
```typescript
interface ParsedCommit {
  type: string;
  scope?: string;
  subject: string;
  body?: string;
  features?: string[];
  tasks?: string[];
}
```

###### `getRecentCommits(limit)`

Gets recent commit history.

```javascript
async getRecentCommits(limit?: number): Promise<Commit[]>
```

### Token Counter

Counts tokens for various AI models.

#### Functions

###### `countTokens(text, model)`

Counts tokens in text.

```javascript
countTokens(text: string, model?: string): number
```

**Supported models:**
- `gpt-3.5-turbo`
- `gpt-4`
- `claude`
- `claude-instant`

###### `estimateCost(tokens, model)`

Estimates cost based on token count.

```javascript
estimateCost(tokens: number, model: string): number
```

### Text Processors

Various text processing utilities.

#### Functions

###### `summarizeText(text, maxLength)`

Creates a summary of text.

```javascript
async summarizeText(
  text: string,
  maxLength?: number
): Promise<string>
```

###### `extractKeywords(text)`

Extracts keywords from text.

```javascript
extractKeywords(text: string): string[]
```

###### `normalizeWhitespace(text)`

Normalizes whitespace in text.

```javascript
normalizeWhitespace(text: string): string
```

---

## Plugin APIs

### Plugin Interface

Standard interface for AIWF plugins.

#### Interface: `AIWFPlugin`

```typescript
interface AIWFPlugin {
  name: string;
  version: string;
  description?: string;
  
  // Lifecycle hooks
  init?(context: PluginContext): Promise<void>;
  destroy?(): Promise<void>;
  
  // Command hooks
  commands?: Record<string, CommandHandler>;
  
  // Event hooks
  hooks?: Record<string, HookHandler>;
}
```

#### Plugin Context

```typescript
interface PluginContext {
  aiwfPath: string;
  projectRoot: string;
  config: AIWFConfig;
  logger: Logger;
  
  // Core services
  resourceLoader: ResourceLoader;
  stateManager: StateIndexManager;
  templateEngine: TemplateEngine;
}
```

### Hook System

Event-driven extension system.

#### Available Hooks

##### Command Lifecycle

```javascript
hooks: {
  'before-command': async (command, args) => { /* ... */ },
  'after-command': async (command, result) => { /* ... */ },
  'command-error': async (command, error) => { /* ... */ }
}
```

##### State Management

```javascript
hooks: {
  'before-state-change': async (oldState, newState) => { /* ... */ },
  'after-state-change': async (oldState, newState) => { /* ... */ },
  'state-checkpoint': async (checkpoint) => { /* ... */ }
}
```

##### Resource Loading

```javascript
hooks: {
  'before-resource-load': async (type, name) => { /* ... */ },
  'after-resource-load': async (type, name, content) => { /* ... */ },
  'resource-not-found': async (type, name) => { /* ... */ }
}
```

---

## AI Integration APIs

### Persona Manager

Manages AI persona configurations and contexts.

#### Class: `AIPersonaManager`

```javascript
import { AIPersonaManager } from 'aiwf/lib/ai-persona-manager';
```

##### Methods

###### `loadPersona(name)`

Loads a persona configuration.

```javascript
async loadPersona(name: string): Promise<Persona>
```

###### `applyPersona(content, persona)`

Applies persona context to content.

```javascript
applyPersona(content: string, persona: Persona): string
```

###### `validatePersona(persona)`

Validates persona configuration.

```javascript
validatePersona(persona: Persona): ValidationResult
```

### Compression Engine

Provides intelligent content compression.

#### Class: `CompressionEngine`

##### Methods

###### `compress(content, strategy)`

Compresses content using specified strategy.

```javascript
async compress(
  content: string,
  strategy: CompressionStrategy
): Promise<CompressedContent>
```

###### `decompress(compressed)`

Decompresses content.

```javascript
async decompress(compressed: CompressedContent): Promise<string>
```

###### `analyzeCompression(content)`

Analyzes potential compression savings.

```javascript
analyzeCompression(content: string): CompressionAnalysis
```

### Evaluation System

Evaluates AI responses and code quality.

#### Class: `EvaluationSystem`

##### Methods

###### `evaluateQuality(content, criteria)`

Evaluates content quality.

```javascript
async evaluateQuality(
  content: string,
  criteria?: EvaluationCriteria
): Promise<QualityScore>
```

###### `compareResponses(responses)`

Compares multiple AI responses.

```javascript
compareResponses(responses: string[]): ComparisonResult
```

###### `generateReport(evaluations)`

Generates evaluation report.

```javascript
generateReport(evaluations: Evaluation[]): EvaluationReport
```

---

## Error Handling

All AIWF APIs follow consistent error handling patterns:

```javascript
try {
  const result = await aiwfApi.someMethod();
} catch (error) {
  if (error.code === 'RESOURCE_NOT_FOUND') {
    // Handle missing resource
  } else if (error.code === 'VALIDATION_ERROR') {
    // Handle validation error
    console.error(error.details);
  } else {
    // Handle unexpected error
    throw error;
  }
}
```

### Error Codes

- `RESOURCE_NOT_FOUND` - Requested resource not found
- `VALIDATION_ERROR` - Input validation failed
- `STATE_CONFLICT` - State operation conflict
- `PERMISSION_DENIED` - Insufficient permissions
- `NETWORK_ERROR` - Network operation failed
- `TIMEOUT` - Operation timed out

---

## Best Practices

### Resource Management

1. Always use ResourceLoader for accessing framework resources
2. Prefer async methods for I/O operations
3. Handle resource not found errors gracefully
4. Cache expensive operations when possible

### State Management

1. Use atomic state updates to prevent conflicts
2. Create checkpoints before major operations
3. Validate state transitions
4. Handle concurrent modifications

### Error Handling

1. Use specific error codes for different scenarios
2. Provide meaningful error messages
3. Include context in error details
4. Log errors appropriately

### Performance

1. Use streaming for large files
2. Implement pagination for lists
3. Cache frequently accessed data
4. Monitor memory usage

---

## Examples

### Creating a Custom Command

```javascript
import { ResourceLoader } from 'aiwf/lib/resource-loader';
import { StateIndexManager } from 'aiwf/lib/state/state-index';

export default class CustomCommand {
  constructor() {
    this.loader = new ResourceLoader();
    this.stateManager = new StateIndexManager('.aiwf');
  }

  async execute(args) {
    // Load current state
    const state = await this.stateManager.loadState();
    
    // Perform operations
    // ...
    
    // Save updated state
    await this.stateManager.saveState(state);
  }
}
```

### Creating a Plugin

```javascript
export default {
  name: 'my-plugin',
  version: '1.0.0',
  
  async init(context) {
    this.logger = context.logger;
    this.logger.info('My plugin initialized');
  },
  
  commands: {
    'my-command': {
      description: 'My custom command',
      handler: async (args, options) => {
        // Command implementation
      }
    }
  },
  
  hooks: {
    'after-state-change': async (oldState, newState) => {
      this.logger.info('State changed', { 
        from: oldState.workflow_mode,
        to: newState.workflow_mode 
      });
    }
  }
};
```

### Using the Compression Engine

```javascript
import { CompressionEngine } from 'aiwf/utils/compression-engine';

const engine = new CompressionEngine();

// Analyze before compression
const analysis = engine.analyzeCompression(largeContent);
console.log(`Potential savings: ${analysis.savingsPercent}%`);

// Compress with specific strategy
const compressed = await engine.compress(largeContent, {
  strategy: 'aggressive',
  preserveStructure: true
});

// Later, decompress
const original = await engine.decompress(compressed);
```

---

## Version History

- **v0.3.x** - Current stable release
  - Complete API redesign
  - Plugin system introduction
  - Enhanced state management
  
- **v0.2.x** - Legacy version
  - Basic command structure
  - Initial resource loader
  
- **v0.1.x** - Initial release
  - Core framework setup

For detailed changelog, see [CHANGELOG.md](../CHANGELOG.md).