aiwf 0.3.15 → 0.3.16

package/docs/ARCHITECTURE.ko.md

@@ -0,0 +1,314 @@
+# AIWF 아키텍처
+
+> AI 워크플로우 프레임워크의 시스템 아키텍처에 대한 종합적인 개요
+
+[한국어](ARCHITECTURE.ko.md) | [English](ARCHITECTURE.md)
+
+## 목차
+
+1. [시스템 개요](#시스템-개요)
+2. [아키텍처 레이어](#아키텍처-레이어)
+3. [핵심 컴포넌트](#핵심-컴포넌트)
+4. [데이터 흐름](#데이터-흐름)
+5. [플러그인 아키텍처](#플러그인-아키텍처)
+6. [보안 고려사항](#보안-고려사항)
+7. [성능 아키텍처](#성능-아키텍처)
+8. [확장성과 향후 확장](#확장성과-향후-확장)
+
+## 시스템 개요
+
+AIWF(AI 워크플로우 프레임워크)는 AI 지원 소프트웨어 개발 워크플로우를 위한 유연하고 확장 가능한 플랫폼을 제공하도록 설계된 모듈식 계층 아키텍처를 기반으로 구축되었습니다.
+
+### 아키텍처 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      CLI 인터페이스 레이어                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │   aiwf CLI   │  │ aiwf-lang   │  │    훅       │            │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
+└─────────┼─────────────────┼─────────────────┼──────────────────┘
+          │                 │                 │
+┌─────────┼─────────────────┼─────────────────┼──────────────────┐
+│         │          코어 엔진 레이어          │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │   명령어     │  │  리소스     │  │   상태      │           │
+│  │  프로세서    │  │   로더      │  │  관리자     │           │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
+│         │                 │                 │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │  템플릿      │  │  플러그인   │  │   토큰      │           │
+│  │   엔진       │  │   시스템    │  │  관리자     │           │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
+└─────────┼─────────────────┼─────────────────┼──────────────────┘
+          │                 │                 │
+┌─────────┼─────────────────┼─────────────────┼──────────────────┐
+│         │      저장소 및 영속성 레이어       │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │    파일      │  │    JSON     │  │    Git      │           │
+│  │   시스템     │  │   저장소    │  │   통합      │           │
+│  └─────────────┘  └─────────────┘  └─────────────┘           │
+└─────────────────────────────────────────────────────────────────┘
+          │                 │                 │
+┌─────────▼─────────────────▼─────────────────▼──────────────────┐
+│                    AI 통합 레이어                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
+│  │  페르소나    │  │   압축      │  │    평가     │           │
+│  │   관리자     │  │   엔진      │  │   시스템    │           │
+│  └─────────────┘  └─────────────┘  └─────────────┘           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 아키텍처 레이어
+
+### 1. CLI 인터페이스 레이어
+AIWF와의 모든 사용자 상호작용을 위한 진입점입니다.
+
+- **aiwf CLI**: Commander.js로 구축된 주요 명령줄 인터페이스
+- **aiwf-lang**: 국제화를 위한 언어 관리 CLI
+- **훅**: Git 훅 및 시스템 통합 지점
+
+### 2. 코어 엔진 레이어
+AIWF 기능의 핵심입니다.
+
+- **명령어 프로세서**: 명령어 라우팅 및 실행
+- **리소스 로더**: 번들 및 사용자 리소스 관리
+- **상태 관리자**: 워크플로우 상태 및 전환 처리
+- **템플릿 엔진**: 프로젝트 템플릿 처리
+- **플러그인 시스템**: 확장성 지원
+- **토큰 관리자**: AI 토큰 사용량 추적 및 최적화
+
+### 3. 저장소 및 영속성 레이어
+모든 데이터 저장 및 검색을 관리합니다.
+
+- **파일 시스템**: 직접 파일 작업 및 캐싱
+- **JSON 저장소**: 구조화된 데이터 영속성
+- **Git 통합**: 버전 관리 시스템 통합
+
+### 4. AI 통합 레이어
+지능형 기능과 AI 지원을 제공합니다.
+
+- **페르소나 관리자**: AI 동작 사용자 정의
+- **압축 엔진**: AI 모델을 위한 컨텍스트 최적화
+- **평가 시스템**: 코드 및 응답 품질 평가
+
+## 핵심 컴포넌트
+
+### 리소스 로더
+
+리소스 로더는 개발 및 프로덕션 환경 모두에서 리소스를 관리하는 중요한 컴포넌트입니다.
+
+```javascript
+// 리소스 로딩 우선순위
+1. 사용자 리소스 (~/.aiwf/)
+2. 프로젝트 리소스 (./.aiwf/)
+3. 번들 리소스 (npm 패키지)
+```
+
+주요 기능:
+- 동적 리소스 검색
+- 폴백 메커니즘
+- 템플릿 및 페르소나 관리
+- 개발 중 핫 리로딩
+
+### 상태 관리자
+
+정교한 워크플로우 기반 상태 관리 시스템을 구현합니다.
+
+```javascript
+// 상태 구조
+{
+  "version": "1.0.0",
+  "lastUpdated": "ISO-8601 타임스탬프",
+  "workflow": {
+    "currentPhase": "development",
+    "currentTask": "task-id",
+    "transitions": []
+  },
+  "tasks": {
+    "task-id": {
+      "status": "in-progress",
+      "dependencies": [],
+      "priority": 0.8
+    }
+  }
+}
+```
+
+기능:
+- 의존성 추적
+- 우선순위 계산
+- 순환 의존성 감지
+- 상태 검증
+- 전환 관리
+
+### 명령어 프로세서
+
+모듈식 설계로 명령어 라우팅 및 실행을 처리합니다.
+
+```javascript
+// 명령어 구조
+export default async function commandName(options) {
+  // 검증
+  // 실행
+  // 상태 업데이트
+  // 결과 포맷팅
+}
+```
+
+### 템플릿 엔진
+
+AIWF 통합이 내장된 프로젝트 스캐폴딩을 제공합니다.
+
+지원되는 템플릿:
+- `api-server`: TypeScript를 사용한 Express.js API
+- `npm-library`: Rollup을 사용한 NPM 패키지
+- `web-app`: Vite를 사용한 React 애플리케이션
+
+### 플러그인 시스템
+
+훅 기반 아키텍처를 통해 확장성을 지원합니다.
+
+```javascript
+// 플러그인 인터페이스
+export interface AIWFPlugin {
+  name: string;
+  version: string;
+  hooks: {
+    beforeCommand?: (command: string, args: any) => void;
+    afterCommand?: (command: string, result: any) => void;
+    beforeStateChange?: (oldState: State, newState: State) => State;
+    afterStateChange?: (state: State) => void;
+  };
+}
+```
+
+## 데이터 흐름
+
+### 명령어 실행 흐름
+
+```
+사용자 입력 → CLI 파서 → 명령어 프로세서 → 명령어 구현
+     ↓                                           ↓
+토큰 추적 ← 상태 업데이트 ← 결과 처리 ← 실행
+     ↓
+사용자 출력
+```
+
+### 리소스 로딩 흐름
+
+```
+리소스 요청 → 사용자 리소스 확인 → 발견? → 반환
+                     ↓ 미발견
+              프로젝트 리소스 확인 → 발견? → 반환
+                     ↓ 미발견
+              번들 리소스 로드 → 반환
+```
+
+### 상태 관리 흐름
+
+```
+명령어 실행 → 사전 검증 → 상태 잠금 → 상태 업데이트
+                                          ↓
+                                     사후 검증
+                                          ↓
+                                   구독자 알림
+                                          ↓
+                                     잠금 해제
+```
+
+## 플러그인 아키텍처
+
+AIWF의 플러그인 시스템은 코어 코드를 수정하지 않고도 기능을 확장할 수 있게 합니다.
+
+### 플러그인 로딩
+
+1. 다음 위치에서 플러그인 스캔:
+   - `~/.aiwf/plugins/`
+   - `./node_modules/aiwf-plugin-*/`
+   - 명시적 플러그인 경로
+
+2. 플러그인 구조 검증
+3. 훅 등록
+4. 플러그인 초기화
+
+### 훅 포인트
+
+- **라이프사이클 훅**: `init`, `destroy`
+- **명령어 훅**: `beforeCommand`, `afterCommand`
+- **상태 훅**: `beforeStateChange`, `afterStateChange`
+- **리소스 훅**: `beforeResourceLoad`, `afterResourceLoad`
+
+## 보안 고려사항
+
+### 입력 검증
+
+모든 사용자 입력은 처리 전에 검증됩니다:
+- 명령어 인수 살균
+- 경로 순회 방지
+- 인젝션 공격 방지
+
+### 리소스 격리
+
+- 사용자 리소스는 시스템 리소스와 격리됨
+- 샌드박스 템플릿 실행
+- 제한된 파일 시스템 접근
+
+### 토큰 보안
+
+- 토큰 수는 로컬에만 저장
+- 토큰 추적에 민감한 데이터 없음
+- 구성 가능한 개인정보 설정
+
+## 성능 아키텍처
+
+### 최적화 전략
+
+1. **지연 로딩**: 명령어와 리소스를 필요시 로드
+2. **캐싱**: 자주 접근하는 리소스를 메모리에 캐시
+3. **병렬 처리**: 독립적인 작업을 동시에 실행
+4. **증분 업데이트**: 변경된 상태 부분만 업데이트
+
+### 메모리 관리
+
+- 템플릿을 위한 리소스 풀링
+- 자동 캐시 제거
+- 메모리 사용량 모니터링
+- 가비지 컬렉션 최적화
+
+### 성능 모니터링
+
+내장 성능 추적:
+- 명령어 실행 시간
+- 리소스 로딩 시간
+- 상태 작업 메트릭
+- 토큰 사용 효율성
+
+## 확장성과 향후 확장
+
+### 계획된 확장
+
+1. **클라우드 동기화**: 기기 간 상태 동기화
+2. **팀 협업**: 공유 워크플로우 및 상태
+3. **커스텀 AI 모델**: 자체 호스팅 모델 지원
+4. **고급 분석**: 상세한 생산성 메트릭
+
+### 확장 포인트
+
+- 사용자 정의 명령어 개발
+- 새로운 템플릿 유형
+- 추가 AI 페르소나
+- 대체 저장소 백엔드
+- 사용자 정의 압축 전략
+
+### API 안정성
+
+AIWF는 시맨틱 버전 관리를 따릅니다:
+- v1.0.0부터 코어 API 안정화
+- 플러그인 API는 별도로 버전 관리
+- 주요 변경사항에 대한 사용 중단 알림
+- 주요 버전에 대한 마이그레이션 가이드
+
+## 결론
+
+AIWF의 아키텍처는 모듈식, 확장 가능, 고성능으로 설계되었습니다. 계층화된 접근 방식은 관심사의 분리를 보장하며, 플러그인 시스템은 코어 안정성을 손상시키지 않으면서 사용자 정의를 가능하게 합니다. 이 아키텍처는 역호환성을 유지하면서 현재 기능과 향후 확장을 모두 지원합니다.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,314 @@
+# AIWF Architecture
+
+> A comprehensive overview of the AI Workflow Framework's system architecture
+
+[한국어](ARCHITECTURE.ko.md) | [English](ARCHITECTURE.md)
+
+## Table of Contents
+
+1. [System Overview](#system-overview)
+2. [Architecture Layers](#architecture-layers)
+3. [Core Components](#core-components)
+4. [Data Flow](#data-flow)
+5. [Plugin Architecture](#plugin-architecture)
+6. [Security Considerations](#security-considerations)
+7. [Performance Architecture](#performance-architecture)
+8. [Scalability and Future Extensions](#scalability-and-future-extensions)
+
+## System Overview
+
+AIWF (AI Workflow Framework) is built on a modular, layered architecture designed to provide a flexible and extensible platform for AI-assisted software development workflows.
+
+### Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      CLI Interface Layer                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │   aiwf CLI   │  │ aiwf-lang   │  │   Hooks     │            │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
+└─────────┼─────────────────┼─────────────────┼──────────────────┘
+          │                 │                 │
+┌─────────┼─────────────────┼─────────────────┼──────────────────┐
+│         │          Core Engine Layer        │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │   Command    │  │  Resource   │  │    State    │           │
+│  │  Processor   │  │   Loader    │  │   Manager   │           │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
+│         │                 │                 │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │  Template    │  │   Plugin    │  │    Token    │           │
+│  │   Engine     │  │   System    │  │   Manager   │           │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
+└─────────┼─────────────────┼─────────────────┼──────────────────┘
+          │                 │                 │
+┌─────────┼─────────────────┼─────────────────┼──────────────────┐
+│         │      Storage & Persistence Layer  │                   │
+│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
+│  │    File      │  │    JSON     │  │    Git      │           │
+│  │   System     │  │   Storage   │  │ Integration │           │
+│  └─────────────┘  └─────────────┘  └─────────────┘           │
+└─────────────────────────────────────────────────────────────────┘
+          │                 │                 │
+┌─────────▼─────────────────▼─────────────────▼──────────────────┐
+│                    AI Integration Layer                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
+│  │   Persona    │  │ Compression │  │  Evaluation │           │
+│  │   Manager    │  │   Engine    │  │   System    │           │
+│  └─────────────┘  └─────────────┘  └─────────────┘           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Architecture Layers
+
+### 1. CLI Interface Layer
+The entry point for all user interactions with AIWF.
+
+- **aiwf CLI**: Main command-line interface built with Commander.js
+- **aiwf-lang**: Language management CLI for internationalization
+- **Hooks**: Git hooks and system integration points
+
+### 2. Core Engine Layer
+The heart of AIWF's functionality.
+
+- **Command Processor**: Routes and executes commands
+- **Resource Loader**: Manages bundled and user resources
+- **State Manager**: Handles workflow state and transitions
+- **Template Engine**: Processes project templates
+- **Plugin System**: Enables extensibility
+- **Token Manager**: Tracks and optimizes AI token usage
+
+### 3. Storage & Persistence Layer
+Manages all data storage and retrieval.
+
+- **File System**: Direct file operations and caching
+- **JSON Storage**: Structured data persistence
+- **Git Integration**: Version control system integration
+
+### 4. AI Integration Layer
+Provides intelligent features and AI assistance.
+
+- **Persona Manager**: AI behavior customization
+- **Compression Engine**: Context optimization for AI models
+- **Evaluation System**: Code and response quality assessment
+
+## Core Components
+
+### Resource Loader
+
+The Resource Loader is a critical component that manages resources in both development and production environments.
+
+```javascript
+// Resource loading priority
+1. User resources (~/.aiwf/)
+2. Project resources (./.aiwf/)
+3. Bundled resources (npm package)
+```
+
+Key features:
+- Dynamic resource discovery
+- Fallback mechanism
+- Template and persona management
+- Hot-reloading in development
+
+### State Manager
+
+Implements a sophisticated workflow-based state management system.
+
+```javascript
+// State structure
+{
+  "version": "1.0.0",
+  "lastUpdated": "ISO-8601 timestamp",
+  "workflow": {
+    "currentPhase": "development",
+    "currentTask": "task-id",
+    "transitions": []
+  },
+  "tasks": {
+    "task-id": {
+      "status": "in-progress",
+      "dependencies": [],
+      "priority": 0.8
+    }
+  }
+}
+```
+
+Features:
+- Dependency tracking
+- Priority calculation
+- Circular dependency detection
+- State validation
+- Transition management
+
+### Command Processor
+
+Handles command routing and execution with a modular design.
+
+```javascript
+// Command structure
+export default async function commandName(options) {
+  // Validation
+  // Execution
+  // State update
+  // Result formatting
+}
+```
+
+### Template Engine
+
+Provides project scaffolding with AIWF integration built-in.
+
+Supported templates:
+- `api-server`: Express.js API with TypeScript
+- `npm-library`: NPM package with Rollup
+- `web-app`: React application with Vite
+
+### Plugin System
+
+Enables extensibility through a hook-based architecture.
+
+```javascript
+// Plugin interface
+export interface AIWFPlugin {
+  name: string;
+  version: string;
+  hooks: {
+    beforeCommand?: (command: string, args: any) => void;
+    afterCommand?: (command: string, result: any) => void;
+    beforeStateChange?: (oldState: State, newState: State) => State;
+    afterStateChange?: (state: State) => void;
+  };
+}
+```
+
+## Data Flow
+
+### Command Execution Flow
+
+```
+User Input → CLI Parser → Command Processor → Command Implementation
+     ↓                                                    ↓
+Token Tracking ← State Update ← Result Processing ← Execution
+     ↓
+User Output
+```
+
+### Resource Loading Flow
+
+```
+Resource Request → Check User Resources → Found? → Return
+                           ↓ Not Found
+                   Check Project Resources → Found? → Return
+                           ↓ Not Found
+                   Load Bundled Resources → Return
+```
+
+### State Management Flow
+
+```
+Command Execution → Pre-validation → State Lock → Update State
+                                                       ↓
+                                              Post-validation
+                                                       ↓
+                                              Notify Subscribers
+                                                       ↓
+                                              Release Lock
+```
+
+## Plugin Architecture
+
+AIWF's plugin system allows for extending functionality without modifying core code.
+
+### Plugin Loading
+
+1. Scan for plugins in:
+   - `~/.aiwf/plugins/`
+   - `./node_modules/aiwf-plugin-*/`
+   - Explicit plugin paths
+
+2. Validate plugin structure
+3. Register hooks
+4. Initialize plugin
+
+### Hook Points
+
+- **Lifecycle Hooks**: `init`, `destroy`
+- **Command Hooks**: `beforeCommand`, `afterCommand`
+- **State Hooks**: `beforeStateChange`, `afterStateChange`
+- **Resource Hooks**: `beforeResourceLoad`, `afterResourceLoad`
+
+## Security Considerations
+
+### Input Validation
+
+All user inputs are validated before processing:
+- Command arguments sanitization
+- Path traversal prevention
+- Injection attack prevention
+
+### Resource Isolation
+
+- User resources are isolated from system resources
+- Sandboxed template execution
+- Limited file system access
+
+### Token Security
+
+- Token counts stored locally only
+- No sensitive data in token tracking
+- Configurable privacy settings
+
+## Performance Architecture
+
+### Optimization Strategies
+
+1. **Lazy Loading**: Commands and resources loaded on-demand
+2. **Caching**: Frequently accessed resources cached in memory
+3. **Parallel Processing**: Independent operations run concurrently
+4. **Incremental Updates**: Only changed state portions updated
+
+### Memory Management
+
+- Resource pooling for templates
+- Automatic cache eviction
+- Memory usage monitoring
+- Garbage collection optimization
+
+### Performance Monitoring
+
+Built-in performance tracking:
+- Command execution time
+- Resource loading time
+- State operation metrics
+- Token usage efficiency
+
+## Scalability and Future Extensions
+
+### Planned Extensions
+
+1. **Cloud Sync**: Synchronize state across devices
+2. **Team Collaboration**: Shared workflows and states
+3. **Custom AI Models**: Support for self-hosted models
+4. **Advanced Analytics**: Detailed productivity metrics
+
+### Extension Points
+
+- Custom command development
+- New template types
+- Additional AI personas
+- Alternative storage backends
+- Custom compression strategies
+
+### API Stability
+
+AIWF follows semantic versioning:
+- Core APIs stable from v1.0.0
+- Plugin APIs versioned separately
+- Deprecation notices for breaking changes
+- Migration guides for major versions
+
+## Conclusion
+
+AIWF's architecture is designed to be modular, extensible, and performant. The layered approach ensures separation of concerns while the plugin system enables customization without compromising core stability. This architecture supports both current features and future expansions while maintaining backward compatibility.