npm - aiwf - Versions diffs - 0.3.23 → 0.4.0 - Mend

aiwf 0.3.23 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (321) hide show

package/docs/API_REFERENCE_FULL.md DELETED Viewed

@@ -1,1135 +0,0 @@
-# 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).