gthinking 1.2.1 → 2.1.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,271 @@
+# gthinking v2.0.0 Architecture
+
+## Overview
+
+The gthinking library is built on a modular, event-driven architecture that enables flexible and extensible sequential thinking workflows.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SequentialThinkingEngine                      │
+│                         (Orchestrator)                           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│    Config    │    │    Cache     │    │   Sessions   │
+│   Manager    │    │   Manager    │    │   Manager    │
+└──────────────┘    └──────────────┘    └──────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│   Search &   │    │   Analysis   │    │   Reasoning  │
+│  Discovery   │    │    Engine    │    │    Engine    │
+└──────────────┘    └──────────────┘    └──────────────┘
+        │                     │                     │
+        └─────────────────────┼─────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│   Learning   │    │   Planning   │    │  Creativity  │
+│    Engine    │    │    Engine    │    │    Engine    │
+└──────────────┘    └──────────────┘    └──────────────┘
+                              │
+                              ▼
+                    ┌──────────────┐
+                    │  Synthesis   │
+                    │    Engine    │
+                    └──────────────┘
+```
+
+## Component Details
+
+### SequentialThinkingEngine
+
+The main orchestrator that coordinates all thinking stages:
+- **Responsibilities**:
+  - Request validation
+  - Stage selection (dynamic or explicit)
+  - Pipeline execution
+  - Result synthesis
+  - Session management
+  - Event emission
+
+### Stage Engines
+
+Each stage is implemented as a separate engine:
+
+#### 1. SearchDiscoveryEngine
+- Web search via multiple providers
+- Knowledge base queries
+- Result aggregation and ranking
+
+#### 2. AnalysisEngine
+- Sentiment analysis
+- Entity extraction
+- Topic modeling
+- Keyword extraction
+- Text summarization
+- Fact checking
+
+#### 3. ReasoningEngine
+- Deductive reasoning
+- Inductive reasoning
+- Abductive reasoning
+- Analogical reasoning
+- Causal reasoning
+- Counterfactual reasoning
+
+#### 4. LearningEngine
+- Pattern recognition
+- Knowledge graph management
+- Context memory
+- User preference learning
+
+#### 5. PlanningEngine
+- Task decomposition
+- Prioritization
+- Resource allocation
+- Timeline generation
+- Risk analysis
+
+#### 6. CreativityEngine
+- Brainstorming
+- SCAMPER technique
+- Six Thinking Hats
+- Mind mapping
+- Out-of-box thinking
+
+#### 7. SynthesisEngine
+- Result aggregation
+- Devil's advocate
+- Confidence calculation
+- Recommendation generation
+
+## Data Flow
+
+```
+1. User Request
+   ↓
+2. Request Validation (Zod Schema)
+   ↓
+3. Cache Check
+   ↓
+4. Stage Selection (Dynamic or Explicit)
+   ↓
+5. Stage Execution
+   ├─ Parallel Stages
+   └─ Sequential Stages
+   ↓
+6. Result Synthesis
+   ↓
+7. Cache Store
+   ↓
+8. Return Result
+```
+
+## Design Patterns
+
+### 1. Strategy Pattern
+Each reasoning type is implemented as a strategy:
+```typescript
+interface ReasoningStrategy {
+  execute(session: ReasoningSession): Promise<void>;
+}
+
+class DeductiveStrategy implements ReasoningStrategy { ... }
+class InductiveStrategy implements ReasoningStrategy { ... }
+```
+
+### 2. Observer Pattern
+Event-driven architecture for monitoring:
+```typescript
+engine.on('thinking:stage:complete', (payload) => {
+  console.log(`Stage ${payload.stage} completed`);
+});
+```
+
+### 3. Factory Pattern
+Engine creation via factory methods:
+```typescript
+const engine = createEngine(config);
+```
+
+### 4. Singleton Pattern
+Shared instances for managers:
+```typescript
+export const cacheManager = new CacheManager();
+export const configManager = new ConfigManager();
+```
+
+### 5. Plugin Pattern
+Extensible architecture for custom functionality:
+```typescript
+interface ThinkingPlugin {
+  name: string;
+  install(engine: SequentialThinkingEngine): void;
+}
+```
+
+## Security Architecture
+
+### Input Sanitization
+- All user inputs sanitized before processing
+- Zod schema validation
+- Shell command injection prevention
+
+### Rate Limiting
+- Per-session rate limiting
+- Configurable limits
+- Automatic throttling
+
+### Error Handling
+- Structured error types
+- Safe error messages (no sensitive info)
+- Retry mechanisms
+
+## Performance Architecture
+
+### Caching Strategy
+- Multi-level caching
+- TTL-based expiration
+- LRU eviction
+- Cache warming
+
+### Parallel Execution
+- Independent stages run in parallel
+- Configurable concurrency
+- Resource pooling
+
+### Streaming Support
+- Real-time result streaming
+- Progressive rendering
+- Backpressure handling
+
+## Extensibility
+
+### Plugin System
+```typescript
+class MyPlugin implements ThinkingPlugin {
+  name = 'my-plugin';
+  
+  install(engine: SequentialThinkingEngine): void {
+    engine.on('thinking:complete', this.onComplete.bind(this));
+  }
+}
+
+engine.use(new MyPlugin());
+```
+
+### Custom Stages
+```typescript
+engine.registerStage('custom', new CustomStageExecutor());
+```
+
+### Custom Providers
+```typescript
+engine.registerLLMProvider('custom', new CustomLLMProvider());
+engine.registerSearchProvider('custom', new CustomSearchProvider());
+```
+
+## Testing Architecture
+
+### Unit Tests
+- Individual engine tests
+- Utility function tests
+- Type validation tests
+
+### Integration Tests
+- Full pipeline tests
+- Multi-engine interaction tests
+- End-to-end tests
+
+### Mock Implementations
+- Mock LLM providers
+- Mock search providers
+- Mock cache implementations
+
+## Deployment Architecture
+
+### NPM Package
+- TypeScript source
+- Compiled JavaScript
+- Type definitions
+- Source maps
+
+### MCP Server
+- Standalone executable
+- Environment configuration
+- Stdio transport
+
+### Docker Support
+- Containerized deployment
+- Environment variable configuration
+- Volume mounting for persistence

package/docs/CHANGELOG.md

@@ -0,0 +1,283 @@
+# Changelog
+
+All notable changes to the gthinking project will be documented in this file.
+
+## [2.1.0] - 2024-02-01
+
+### New Features
+
+#### LLM Integration
+- **CLI Provider**: Added support for using local CLI tools as LLM providers (`provider: 'cli'`).
+- **No API Key Mode**: Ability to run without API keys by leveraging local CLI authentication (OAuth).
+- **Flexible Configuration**:
+  - `cliCommand`: Specify any executable command.
+  - `cliArgs`: Pass custom arguments to the CLI tool.
+  - `promptPassingMethod`: Choose between `stdin` (streaming safe) or `arg` (flag based).
+  - `promptFlag`: Customize the prompt flag (e.g., `-p`, `--query`).
+- **Smart Defaults**: Auto-configuration for common tools like `gemini` (automatically sets `-p` flag).
+
+### Security
+- **Secure Spawn**: Implemented `spawn` with non-shell execution to prevent command injection in CLI mode.
+- **Stream Handling**: Improved stream backpressure management to prevent memory leaks in CLI mode.
+
+## [2.0.0] - 2024-01-01
+
+### Major Changes
+
+#### Security
+- **BREAKING**: Replaced shell command execution with HTTP API calls for LLM providers
+- Added comprehensive input sanitization to prevent injection attacks
+- Implemented rate limiting to prevent abuse
+- Added security configuration options
+- Removed all command-line tool dependencies
+
+#### Architecture
+- Complete rewrite with modular architecture
+- Implemented plugin system for extensibility
+- Added support for parallel stage execution
+- Implemented streaming response support
+- Added event-driven architecture with EventEmitter
+
+#### Performance
+- Implemented multi-level caching with TTL support
+- Added cache warming and preloading
+- Implemented LRU eviction strategy
+- Added parallel execution for independent stages
+- Implemented streaming for real-time results
+
+#### Error Handling
+- Added structured error types (GThinkingError, ValidationError, TimeoutError, etc.)
+- Implemented retry mechanisms with exponential backoff
+- Added error recovery strategies
+- Implemented error event emission
+- Added comprehensive error logging
+
+#### Type Safety
+- Migrated to strict TypeScript mode
+- Added comprehensive Zod schemas for all inputs
+- Removed all `any` types
+- Added strict null checks
+- Implemented comprehensive type definitions
+
+#### Testing
+- Added Jest testing framework
+- Implemented unit tests for all modules
+- Added integration tests
+- Set up code coverage reporting (80%+ target)
+- Added test utilities and mocks
+
+#### Configuration
+- Added centralized configuration management
+- Implemented environment variable loading
+- Added configuration validation
+- Added support for custom validators
+- Implemented configuration merging
+
+#### Logging
+- Implemented Winston logging framework
+- Added structured logging support
+- Implemented log levels (debug, info, warn, error)
+- Added file and console transport options
+- Implemented performance logging
+
+#### Metrics
+- Added metrics collection system
+- Implemented counter, gauge, histogram, and timer metrics
+- Added Prometheus export format
+- Implemented performance tracking decorators
+- Added operation tracking utilities
+
+#### Cache
+- Implemented in-memory cache with TTL
+- Added LRU eviction strategy
+- Implemented cache statistics
+- Added cache persistence options
+- Implemented memoization decorator
+
+### New Features
+
+#### Core Engine
+- Dynamic pipeline selection based on query analysis
+- Session management with cleanup
+- Cache key generation
+- Stage dependency management
+- Result synthesis
+
+#### Search & Discovery
+- Multi-provider search support (Google, Bing, Brave, DuckDuckGo)
+- Result aggregation and ranking
+- Conflict detection
+- Consensus scoring
+- Knowledge base integration
+
+#### Analysis
+- Sentiment analysis with emotion detection
+- Entity extraction (people, organizations, locations, etc.)
+- Topic extraction
+- Keyword extraction with TF-IDF
+- Text summarization (extractive and abstractive)
+- Fact checking
+- Language detection
+- Readability analysis
+
+#### Reasoning
+- 6 types of reasoning (deductive, inductive, abductive, analogical, causal, counterfactual)
+- Chain of Thought generation
+- Hypothesis management
+- Problem decomposition
+- Logical rule engine
+
+#### Planning
+- Task decomposition
+- Prioritization with multiple criteria
+- Resource allocation
+- Timeline generation with critical path
+- Risk analysis
+
+#### Creativity
+- Brainstorming with multiple techniques
+- SCAMPER analysis
+- Six Thinking Hats
+- Mind mapping
+- Out-of-box thinking perspectives
+- Concept connection
+
+#### Learning
+- Pattern recognition
+- Knowledge graph management
+- Context memory
+- User preference learning
+- Interaction recording
+
+#### Synthesis
+- Result aggregation
+- Devil's advocate mode
+- Confidence calculation
+- Recommendation generation
+- Output formatting
+
+### Improvements
+
+#### Code Quality
+- Added ESLint configuration
+- Implemented strict TypeScript rules
+- Added JSDoc documentation
+- Implemented code formatting
+- Added pre-commit hooks
+
+#### Documentation
+- Added comprehensive README
+- Added architecture documentation
+- Added API reference
+- Added usage examples
+- Added troubleshooting guide
+
+#### Developer Experience
+- Added TypeScript declaration maps
+- Implemented source maps
+- Added hot reload for development
+- Implemented debug logging
+- Added development utilities
+
+### Bug Fixes
+
+#### Security
+- Fixed command injection vulnerability in LLM service
+- Fixed input validation bypass
+- Fixed regex ReDoS vulnerabilities
+- Fixed unsafe JSON parsing
+
+#### Stability
+- Fixed memory leaks in session management
+- Fixed event listener leaks
+- Fixed cache cleanup issues
+- Fixed timeout handling
+
+#### Performance
+- Fixed blocking operations
+- Fixed unnecessary re-renders
+- Fixed cache thrashing
+- Fixed memory bloat
+
+### Removed
+
+#### Deprecated Features
+- Removed shell command execution
+- Removed exec/spawn usage
+- Removed hardcoded API keys
+- Removed insecure random number generation
+
+#### Unused Code
+- Removed commented code
+- Removed unused imports
+- Removed dead code paths
+- Removed unused dependencies
+
+### Dependencies
+
+#### Added
+- `uuid` - UUID generation
+- `winston` - Logging framework
+- `axios` - HTTP client
+- `jest` - Testing framework
+- `@types/jest` - Jest type definitions
+- `ts-jest` - TypeScript Jest preprocessor
+- `@typescript-eslint/*` - TypeScript ESLint plugins
+
+#### Updated
+- `typescript` to 5.3.3
+- `zod` to 3.22.4
+- `@modelcontextprotocol/sdk` to 1.25.3
+
+#### Removed
+- `exec` and `spawn` dependencies
+- Unused utility libraries
+- Deprecated type definitions
+
+## [1.3.0] - 2023-12-15
+
+### Added
+- Dynamic Pipeline feature
+- Devil's Advocate Mode
+- Dynamic Planning in PlanningEngine
+
+### Security
+- Fixed Command Injection Vulnerability (changed from exec to spawn)
+
+### Refactoring
+- Split large types.ts into modules
+- Added Dependency Injection support
+
+## [1.2.1] - 2023-12-10
+
+### Security
+- Security fix for command injection
+
+### Architecture
+- Added Dependency Injection in SequentialThinkingEngine
+
+## [1.2.0] - 2023-12-05
+
+### Added
+- New reasoning types
+- Enhanced creativity techniques
+- Improved learning algorithms
+
+## [1.1.0] - 2023-11-20
+
+### Added
+- MCP server support
+- Additional search providers
+- Enhanced analysis features
+
+## [1.0.0] - 2023-11-01
+
+### Initial Release
+- Basic sequential thinking pipeline
+- Search and discovery
+- Analysis engine
+- Reasoning engine
+- Planning engine
+- Creativity engine
+- Learning engine
+- Synthesis engine

package/jest.config.js

@@ -0,0 +1,28 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/examples.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 20,
+      functions: 20,
+      lines: 20,
+      statements: 20,
+    },
+  },
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],
+};

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "gthinking",
-  "version": "1.2.1",
-  "description": "A comprehensive intelligent sequential thinking framework for complex problem solving",
+  "version": "2.1.1",
+  "description": "Sequential Thinking System v2.1 - Advanced multi-stage thinking engine with AI-powered analysis, reasoning, and planning. Now supports local CLI tools!",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
-    "gthinking": "dist/server.js"
+    "gthinking": "dist/mcp/server.js"
   },
-  "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc && chmod +x dist/server.js",
-    "dev": "ts-node examples.ts",
-    "test": "jest",
+    "build": "tsc && chmod +x dist/mcp/server.js",
+    "dev": "ts-node src/examples.ts",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
     "lint": "eslint . --ext .ts",
-    "clean": "rm -rf dist"
+    "lint:fix": "eslint . --ext .ts --fix",
+    "clean": "rm -rf dist coverage",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "keywords": [
     "ai",
@@ -24,33 +27,43 @@
     "learning",
     "search",
     "nlp",
-    "decision-making"
+    "decision-making",
+    "mcp",
+    "sequential-thinking"
   ],
-  "author": "Sequential Thinking Team",
+  "author": "Gotza02",
   "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.3",
-    "events": "^3.3.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0",
-    "jest": "^29.0.0",
-    "ts-node": "^10.9.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-org/sequential-thinking-system.git"
+    "url": "https://github.com/gotza02/gthinking.git"
   },
   "bugs": {
-    "url": "https://github.com/your-org/sequential-thinking-system/issues"
+    "url": "https://github.com/gotza02/gthinking/issues"
+  },
+  "homepage": "https://github.com/gotza02/gthinking#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.6.5",
+    "eventemitter3": "^5.0.4",
+    "events": "^3.3.0",
+    "rate-limiter-flexible": "^9.0.1",
+    "uuid": "^9.0.1",
+    "winston": "^3.11.0",
+    "zod": "^3.22.4"
   },
-  "homepage": "https://github.com/your-org/sequential-thinking-system#readme"
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.6",
+    "@types/uuid": "^9.0.7",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
 }