gthinking 1.2.1 → 2.1.1

package/dist/utils/validation.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * Validation Utility for gthinking v2.0.0
+ * Input sanitization and validation functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validationRateLimiter = exports.ValidationRateLimiter = void 0;
+exports.sanitizeInput = sanitizeInput;
+exports.sanitizeForShell = sanitizeForShell;
+exports.validateEmail = validateEmail;
+exports.isValidURL = isValidURL;
+exports.isNonEmptyString = isNonEmptyString;
+exports.isPositiveInteger = isPositiveInteger;
+exports.isInRange = isInRange;
+exports.hasUniqueElements = hasUniqueElements;
+exports.safeJsonParse = safeJsonParse;
+exports.safeJsonStringify = safeJsonStringify;
+exports.validateSchema = validateSchema;
+exports.validateSchemaAsync = validateSchemaAsync;
+exports.hasRequiredProperties = hasRequiredProperties;
+exports.isValidLength = isValidLength;
+exports.removeNullValues = removeNullValues;
+exports.deepClone = deepClone;
+exports.isPlainObject = isPlainObject;
+const zod_1 = require("zod");
+const errors_1 = require("../core/errors");
+/**
+ * Sanitize user input to prevent injection attacks
+ * @param input - The input string to sanitize
+ * @returns Sanitized string
+ */
+function sanitizeInput(input) {
+    if (!input)
+        return '';
+    // Remove potentially dangerous characters
+    return input
+        .replace(/[<>]/g, '') // Remove HTML tags
+        .replace(/[&;|`$(){}[\]\\]/g, '') // Remove shell metacharacters
+        .replace(/\0/g, '') // Remove null bytes
+        .trim();
+}
+/**
+ * Sanitize a string for use in shell commands
+ * @param input - The input string to sanitize
+ * @returns Shell-safe string
+ */
+function sanitizeForShell(input) {
+    if (!input)
+        return '';
+    // More aggressive sanitization for shell usage
+    // Only allow alphanumeric, underscore, hyphen, dot, and space
+    return input
+        .replace(/[^a-zA-Z0-9_\-\s.]/g, '')
+        .trim();
+}
+/**
+ * Validate and sanitize an email address
+ * @param email - The email to validate
+ * @returns Validated email or null if invalid
+ */
+function validateEmail(email) {
+    const emailSchema = zod_1.z.string().email();
+    const result = emailSchema.safeParse(email);
+    return result.success ? result.data : null;
+}
+/**
+ * Validate a URL string
+ * @param url - The URL to validate
+ * @returns True if the URL is valid
+ */
+function isValidURL(url) {
+    try {
+        new URL(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate that a string is not empty or whitespace only
+ * @param str - The string to validate
+ * @returns True if the string has content
+ */
+function isNonEmptyString(str) {
+    return typeof str === 'string' && str.trim().length > 0;
+}
+/**
+ * Validate that a value is a positive integer
+ * @param value - The value to validate
+ * @returns True if the value is a positive integer
+ */
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * Validate that a value is within a range
+ * @param value - The value to validate
+ * @param min - The minimum allowed value
+ * @param max - The maximum allowed value
+ * @returns True if the value is within the range
+ */
+function isInRange(value, min, max) {
+    return value >= min && value <= max;
+}
+/**
+ * Validate an array has unique elements
+ * @param arr - The array to validate
+ * @returns True if all elements are unique
+ */
+function hasUniqueElements(arr) {
+    return new Set(arr).size === arr.length;
+}
+/**
+ * Safe JSON parse with error handling
+ * @param json - The JSON string to parse
+ * @returns Parsed object or null if invalid
+ */
+function safeJsonParse(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Safe JSON stringify with error handling
+ * @param obj - The object to stringify
+ * @returns JSON string or null if failed
+ */
+function safeJsonStringify(obj) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate schema with detailed error messages
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @returns Validated data
+ * @throws ValidationError if validation fails
+ */
+function validateSchema(schema, data) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const errors = result.error.errors.map(err => ({
+            path: err.path.join('.'),
+            message: err.message,
+            code: err.code,
+        }));
+        throw new errors_1.ValidationError(`Validation failed: ${errors.map(e => `${e.path}: ${e.message}`).join(', ')}`, { errors });
+    }
+    return result.data;
+}
+/**
+ * Validate schema asynchronously
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @returns Promise of validated data
+ * @throws ValidationError if validation fails
+ */
+async function validateSchemaAsync(schema, data) {
+    const result = await schema.safeParseAsync(data);
+    if (!result.success) {
+        const errors = result.error.errors.map(err => ({
+            path: err.path.join('.'),
+            message: err.message,
+            code: err.code,
+        }));
+        throw new errors_1.ValidationError(`Validation failed: ${errors.map(e => `${e.path}: ${e.message}`).join(', ')}`, { errors });
+    }
+    return result.data;
+}
+/**
+ * Check if an object has all required properties
+ * @param obj - The object to check
+ * @param requiredProps - The required property names
+ * @returns True if all properties exist
+ */
+function hasRequiredProperties(obj, requiredProps) {
+    return requiredProps.every(prop => prop in obj && obj[prop] !== undefined);
+}
+/**
+ * Validate that a string length is within bounds
+ * @param str - The string to validate
+ * @param min - Minimum length (inclusive)
+ * @param max - Maximum length (inclusive)
+ * @returns True if the string length is valid
+ */
+function isValidLength(str, min, max) {
+    const length = str.length;
+    return length >= min && length <= max;
+}
+/**
+ * Remove null and undefined values from an object
+ * @param obj - The object to clean
+ * @returns Object with null/undefined values removed
+ */
+function removeNullValues(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== null && v !== undefined));
+}
+/**
+ * Deep clone an object
+ * @param obj - The object to clone
+ * @returns Deep cloned object
+ */
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/**
+ * Check if a value is a plain object
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ */
+function isPlainObject(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && value.constructor === Object;
+}
+/**
+ * Rate limiter for validation attempts
+ */
+class ValidationRateLimiter {
+    attempts = new Map();
+    maxAttempts;
+    windowMs;
+    constructor(maxAttempts = 5, windowMs = 60000) {
+        this.maxAttempts = maxAttempts;
+        this.windowMs = windowMs;
+    }
+    /**
+     * Check if a key is rate limited
+     * @param key - The key to check
+     * @returns True if the key is rate limited
+     */
+    isRateLimited(key) {
+        const now = Date.now();
+        const attempts = this.attempts.get(key) || [];
+        // Remove old attempts outside the window
+        const validAttempts = attempts.filter(time => now - time < this.windowMs);
+        return validAttempts.length >= this.maxAttempts;
+    }
+    /**
+     * Record an attempt for a key
+     * @param key - The key to record
+     */
+    recordAttempt(key) {
+        const now = Date.now();
+        const attempts = this.attempts.get(key) || [];
+        attempts.push(now);
+        this.attempts.set(key, attempts);
+    }
+    /**
+     * Reset attempts for a key
+     * @param key - The key to reset
+     */
+    reset(key) {
+        this.attempts.delete(key);
+    }
+    /**
+     * Clear all attempts
+     */
+    clear() {
+        this.attempts.clear();
+    }
+}
+exports.ValidationRateLimiter = ValidationRateLimiter;
+// Export a singleton instance
+exports.validationRateLimiter = new ValidationRateLimiter();
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/docs/API.md

@@ -0,0 +1,411 @@
+# gthinking v2.0.0 API Reference
+
+## SequentialThinkingEngine
+
+The main orchestrator class for the sequential thinking system.
+
+### Constructor
+
+```typescript
+new SequentialThinkingEngine(config?: Partial<GThinkingConfig>)
+```
+
+**Parameters:**
+- `config` - Optional configuration object
+
+**Example:**
+```typescript
+const engine = new SequentialThinkingEngine({
+  llm: { provider: 'gemini', apiKey: 'your-key' },
+  cache: { enabled: true, maxSize: 2000 },
+});
+```
+
+### Methods
+
+#### think()
+
+Execute the full thinking pipeline.
+
+```typescript
+think(request: ThinkingRequest): Promise<SynthesisResult>
+```
+
+**Parameters:**
+- `request` - The thinking request object
+
+**Returns:** Promise resolving to SynthesisResult
+
+**Example:**
+```typescript
+const result = await engine.think({
+  query: 'How can we improve remote work productivity?',
+  preferredStages: ['search', 'analysis', 'reasoning', 'synthesis'],
+  options: {
+    depth: 'deep',
+    complexity: 'complex',
+  },
+});
+```
+
+#### quickSearch()
+
+Execute a quick search with minimal stages.
+
+```typescript
+quickSearch(query: string): Promise<SynthesisResult>
+```
+
+**Example:**
+```typescript
+const result = await engine.quickSearch('AI ethics guidelines');
+```
+
+#### deepAnalysis()
+
+Execute a comprehensive analysis with all stages.
+
+```typescript
+deepAnalysis(query: string): Promise<SynthesisResult>
+```
+
+**Example:**
+```typescript
+const result = await engine.deepAnalysis('Climate change mitigation strategies');
+```
+
+#### creativeSolve()
+
+Solve a problem using creative thinking techniques.
+
+```typescript
+creativeSolve(challenge: string): Promise<CreativeResult>
+```
+
+**Example:**
+```typescript
+const result = await engine.creativeSolve('Increase customer engagement');
+```
+
+#### createPlan()
+
+Create an execution plan for a goal.
+
+```typescript
+createPlan(goal: string): Promise<Plan>
+```
+
+**Example:**
+```typescript
+const plan = await engine.createPlan('Launch a mobile app');
+```
+
+### Events
+
+The engine emits the following events:
+
+#### thinking:start
+
+Emitted when a thinking session starts.
+
+```typescript
+engine.on('thinking:start', ({ sessionId, request }) => {
+  console.log(`Session ${sessionId} started`);
+});
+```
+
+#### thinking:stage:start
+
+Emitted when a stage starts.
+
+```typescript
+engine.on('thinking:stage:start', ({ sessionId, stage }) => {
+  console.log(`Stage ${stage} started for session ${sessionId}`);
+});
+```
+
+#### thinking:stage:complete
+
+Emitted when a stage completes.
+
+```typescript
+engine.on('thinking:stage:complete', ({ sessionId, stage, result }) => {
+  console.log(`Stage ${stage} completed with confidence ${result.confidence}`);
+});
+```
+
+#### thinking:complete
+
+Emitted when the thinking process completes.
+
+```typescript
+engine.on('thinking:complete', ({ sessionId, result }) => {
+  console.log(`Session ${sessionId} completed`);
+});
+```
+
+## Types
+
+### ThinkingRequest
+
+```typescript
+interface ThinkingRequest {
+  id?: string;                    // Optional session ID
+  query: string;                  // The query to process
+  context?: string[];             // Additional context
+  preferredStages?: ThinkingStage[]; // Stages to execute
+  options?: {
+    depth?: 'shallow' | 'medium' | 'deep';
+    complexity?: 'simple' | 'moderate' | 'complex';
+    timeout?: number;
+    maxStages?: number;
+    stream?: boolean;
+  };
+}
+```
+
+### SynthesisResult
+
+```typescript
+interface SynthesisResult {
+  success: boolean;
+  confidence: number;
+  timestamp: Date;
+  duration: number;
+  errors: string[];
+  query: string;
+  summary: string;
+  keyFindings: string[];
+  recommendations: Recommendation[];
+  evaluation: EvaluationResult[];
+  devilsAdvocate: DevilsAdvocatePoint[];
+  confidenceBreakdown: ConfidenceBreakdown;
+  nextSteps: string[];
+  additionalConsiderations: string[];
+  sources: Source[];
+  metadata: Record<string, unknown>;
+}
+```
+
+### Recommendation
+
+```typescript
+interface Recommendation {
+  id: string;
+  priority: number;  // 1-5
+  title: string;
+  description: string;
+  rationale: string;
+  confidence: number;
+  actions: string[];
+  expectedOutcome: string;
+  risks: string[];
+  resources: string[];
+  timeline?: string;
+}
+```
+
+## Configuration
+
+### GThinkingConfig
+
+```typescript
+interface GThinkingConfig {
+  version: string;
+  llm: LLMProviderConfig;
+  search: SearchConfig;
+  cache: CacheConfig;
+  logging: LoggingConfig;
+  pipeline: PipelineConfig;
+  security: SecurityConfig;
+  session: SessionConfig;
+  metrics: MetricsConfig;
+}
+```
+
+### LLMProviderConfig
+
+```typescript
+interface LLMProviderConfig {
+  provider: 'gemini' | 'claude' | 'openai' | 'kimi' | 'custom';
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+  timeout: number;
+  maxRetries: number;
+  rateLimitPerMinute: number;
+}
+```
+
+### SearchConfig
+
+```typescript
+interface SearchConfig {
+  enabled: boolean;
+  providers: ('google' | 'bing' | 'brave' | 'duckduckgo')[];
+  apiKeys: Record<string, string>;
+  maxResults: number;
+  timeout: number;
+  cacheResults: boolean;
+  cacheTTL: number;
+}
+```
+
+## Error Handling
+
+### Error Types
+
+```typescript
+import {
+  GThinkingError,
+  ValidationError,
+  TimeoutError,
+  StageError,
+  LLMError,
+  SearchError,
+} from 'gthinking';
+
+try {
+  const result = await engine.think({ query: '...' });
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log(`Timeout in stage: ${error.stage}`);
+  } else if (error instanceof ValidationError) {
+    console.log('Validation failed:', error.details);
+  } else if (error instanceof StageError) {
+    console.log(`Stage ${error.stage} failed: ${error.message}`);
+  }
+}
+```
+
+## Utility Functions
+
+### ID Generation
+
+```typescript
+import { generateUUID, generateShortId, isValidUUID } from 'gthinking';
+
+const uuid = generateUUID();           // Random UUID v4
+const shortId = generateShortId();     // Short random string
+const isValid = isValidUUID(uuid);     // Validate UUID
+```
+
+### Validation
+
+```typescript
+import { sanitizeInput, validateSchema } from 'gthinking';
+
+const clean = sanitizeInput(userInput);
+const result = validateSchema(MySchema, data);
+```
+
+### Logging
+
+```typescript
+import { Logger, info, error } from 'gthinking';
+
+const logger = new Logger('MyComponent');
+logger.info('Operation completed');
+logger.error('Operation failed', { error });
+
+// Or use global functions
+info('Message');
+error('Error message', { details });
+```
+
+### Caching
+
+```typescript
+import { Cache, cacheManager } from 'gthinking';
+
+const cache = new Cache<string>({ maxSize: 1000, defaultTTL: 3600000 });
+cache.set('key', 'value');
+const value = cache.get('key');
+
+// Or use cache manager
+const searchCache = cacheManager.getCache<string>('search');
+```
+
+### Metrics
+
+```typescript
+import { metricsCollector, timed } from 'gthinking';
+
+// Record metrics
+metricsCollector.counter('requests', 1);
+metricsCollector.gauge('active_sessions', 5);
+
+// Time a function
+const timer = metricsCollector.startTimer('operation');
+// ... do work
+metricsCollector.endTimer(timer);
+
+// Or use decorator
+class MyClass {
+  @timed('myMethod')
+  async myMethod() {
+    // ...
+  }
+}
+```
+
+## MCP Server
+
+### Configuration
+
+```json
+{
+  "mcpServers": {
+    "gthinking": {
+      "command": "npx",
+      "args": ["-y", "gthinking"],
+      "env": {
+        "LLM_PROVIDER": "gemini",
+        "LLM_API_KEY": "your-api-key",
+        "GTHINKING_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+### Available Tools
+
+#### think
+
+Execute full thinking pipeline.
+
+**Input:**
+```json
+{
+  "query": "string",
+  "preferredStages": ["search", "analysis", "reasoning", "synthesis"],
+  "options": {
+    "depth": "deep",
+    "complexity": "complex"
+  }
+}
+```
+
+#### quick_search
+
+Execute quick search.
+
+**Input:**
+```json
+{
+  "query": "string"
+}
+```
+
+#### creative_solve
+
+Solve problem creatively.
+
+**Input:**
+```json
+{
+  "challenge": "string",
+  "techniques": ["brainstorming", "scamper"]
+}
+```