fastv0/README.md

Fast File System Operations and AI Integration for Node.js - Like Cursor's token management

# FastV0

A powerful Node.js SDK for file system operations and AI integration, designed specifically for AI assistants and automation tools. Think of it as the Node.js equivalent of Cursor's token management and file operations.

## Features

- **File Management**: Read, write, and manage files with AI integration
- **Desktop Scanner**: Scan and analyze desktop files across different operating systems
- **Token Management**: Optimize AI context with token offloading/onloading (like Cursor)
- **AI Integration**: Connect with multiple AI providers (OpenAI, Groq, Anthropic, Google)
- **Smart Caching**: Intelligent caching system for file analysis and context management
- **TypeScript Support**: Full TypeScript support with type definitions

## Installation

```bash
npm install fastv0
```

## Quick Start

### Basic File Operations

```typescript
import { FileManager } from 'fastv0';

const fm = new FileManager();

// Read a file
const result = await fm.readFile('example.js');
if (result.success) {
  console.log(`File content: ${result.content}`);
}

// Write a file
await fm.writeFile('output.txt', 'Hello, FastV0!');

// List files in directory
const files = await fm.listFiles('./', true);
console.log(`Found ${files.count} files`);
```

### Desktop Scanning

```typescript
import { DesktopScanner } from 'fastv0';

const scanner = new DesktopScanner();

// Scan desktop
const desktopInfo = await scanner.scanDesktop();
console.log(`Found ${desktopInfo.totalFiles} files on desktop`);

// Find specific files
const pythonFiles = await scanner.findDesktopFiles('.py');
console.log(`Found ${pythonFiles.totalFiles} Python files`);

// Analyze desktop structure
const analysis = await scanner.analyzeDesktopStructure();
console.log(`Desktop analysis:`, analysis.analysis);
```

### Token Management (Cursor-like)

```typescript
import { TokenManager } from 'fastv0';

const tm = new TokenManager();

// Offload context to save tokens
const context = { messages: [...], files: [...], analysis: [...] };
const offloadResult = await tm.offloadContext(context);
console.log(`Context offloaded: ${offloadResult.contextId}`);

// Load context back
const onloadResult = await tm.onloadContext(offloadResult.contextId!);
console.log(`Context loaded:`, onloadResult.context);

// Optimize context to fit token limits
const optimized = await tm.optimizeContext(context, 4000);
console.log(`Optimized: ${optimized.optimized}`);
```

### AI Integration

```typescript
import { AIIntegration } from 'fastv0';

// Initialize with API keys
const ai = new AIIntegration({
  groq: 'your-groq-api-key',
  openai: 'your-openai-api-key',
  anthropic: 'your-anthropic-api-key',
  google: 'your-google-api-key'
});

// Analyze file content
const analysis = await ai.analyzeFileContent(
  'function hello() { console.log("Hello, World!"); }',
  'javascript',
  'groq'
);
console.log(`Analysis: ${analysis.analysis}`);

// Generate file summary
const summary = await ai.generateFileSummary(
  'your code here...',
  'typescript'
);
console.log(`Summary: ${summary.analysis}`);
```

### Complete Workflow

```typescript
import { FastV0 } from 'fastv0';

const fastv0 = new FastV0({
  apiKeys: {
    groq: 'your-groq-api-key'
  }
});

// Run complete workflow
const result = await fastv0.completeWorkflow();
console.log(`Desktop scan: ${result.desktopScan?.totalFiles} files`);
console.log(`AI analyses: ${result.analyses?.length} files analyzed`);
```

## CLI Tools

```bash
# Scan desktop
npx fastv0 scan

# Analyze a file
npx fastv0 analyze example.js
npx fastv0 analyze example.js --provider groq

# List files
npx fastv0 list ./src
npx fastv0 list ./src --recursive

# Search files
npx fastv0 search ./src "function"

# Cache operations
npx fastv0 cache info
npx fastv0 cache cleanup

# Complete workflow
npx fastv0 workflow
```

## API Reference

### FileManager

- `readFile(filePath, encoding?)` - Read file content
- `writeFile(filePath, content, encoding?)` - Write file content
- `listFiles(directory, recursive?, extensions?)` - List files
- `searchFiles(directory, query, fileTypes?)` - Search files
- `getFileInfo(filePath)` - Get file metadata

### DesktopScanner

- `scanDesktop(includeHidden?)` - Scan desktop files
- `findDesktopFiles(extension?, nameContains?)` - Find specific files
- `analyzeDesktopStructure()` - Analyze desktop organization
- `getDesktopInfo()` - Get desktop information

### TokenManager

- `offloadContext(context, contextId?)` - Save context to disk
- `onloadContext(contextId)` - Load context from disk
- `optimizeContext(context, maxTokens?)` - Optimize for token limits
- `manageConversationHistory(messages, maxMessages?)` - Manage chat history
- `cacheFileAnalysis(filePath, analysis)` - Cache analysis results
- `cleanupCache(maxAgeHours?)` - Clean old cache files

### AIIntegration

- `analyzeFileContent(content, fileType, provider?)` - AI file analysis
- `generateFileSummary(content, fileType)` - Generate file summary
- `suggestImprovements(content, fileType)` - Suggest code improvements
- `detectCodeIssues(content, fileType)` - Detect code issues
- `batchAnalyzeFiles(files, provider?)` - Batch analysis

### FastV0 (Main Class)

- `analyzeFile(filePath, provider?)` - Quick file analysis
- `scanAndAnalyzeDesktop(provider?)` - Scan and analyze desktop
- `optimizeAndCache(context, maxTokens?)` - Optimize and cache context
- `completeWorkflow(provider?)` - Run complete workflow

## Configuration

### Environment Variables

```bash
# API Keys
export GROQ_API_KEY="your-groq-key"
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GOOGLE_API_KEY="your-google-key"

# Cache Directory
export FASTV0_CACHE_DIR="/path/to/cache"
```

### Configuration Object

```typescript
import { FastV0 } from 'fastv0';

const fastv0 = new FastV0({
  basePath: '/path/to/base',
  maxFileSize: 10 * 1024 * 1024, // 10MB
  maxTokens: 4000,
  apiKeys: {
    groq: 'your-groq-key',
    openai: 'your-openai-key',
    anthropic: 'your-anthropic-key',
    google: 'your-google-key'
  },
  cache: {
    enabled: true,
    maxAge: 24, // hours
    compression: true,
    directory: '/path/to/cache'
  }
});
```

## Advanced Usage

### Custom AI Provider

```typescript
import { AIIntegration } from 'fastv0';

class CustomAIProvider extends AIIntegration {
  async analyzeFileContent(content: string, fileType: string, provider: string = 'custom') {
    // Your custom AI integration
    return {
      success: true,
      analysis: 'Custom analysis result',
      provider: 'custom',
      fileType: fileType,
      analyzedAt: new Date().toISOString()
    };
  }
}
```

### Batch Processing

```typescript
import { FileManager, AIIntegration } from 'fastv0';

const fm = new FileManager();
const ai = new AIIntegration({ groq: 'your-api-key' });

// Get all JavaScript files
const jsFiles = await fm.listFiles('./src', true, ['.js', '.ts']);

// Analyze all files
const analyses = [];
for (const file of jsFiles.files || []) {
  const content = await fm.readFile(file.path);
  if (content.success) {
    const analysis = await ai.analyzeFileContent(content.content!, file.extension);
    analyses.push({ file: file.path, analysis });
  }
}

console.log(`Analyzed ${analyses.length} files`);
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: [Report bugs and request features](https://github.com/fastv0/fastv0/issues)
- Documentation: [Read the full documentation](https://fastv0.readthedocs.io/)
- Discord: [Join our community](https://discord.gg/fastv0)

## Changelog

### v1.0.0
- Initial release
- File management operations
- Desktop scanning
- Token management system
- AI integration with multiple providers
- Smart caching system
- TypeScript support
- CLI tools