@far-world-labs/verblets 0.2.0 → 0.3.2

package/DEVELOPING.md

@@ -1,105 +0,0 @@
-# Developing Verblets
-
-This document explains the development workflow and testing strategy for the Verblets library.
-
-## Testing Strategy
-
-The Verblets library uses a dual testing approach with two types of test files:
-
-### 1. Spec Files (`*.spec.js`)
-- **Purpose**: Deterministic unit tests with mocked LLM responses
-- **Reliability**: Should always pass consistently
-- **LLM Usage**: Uses mocked responses, no actual API calls
-- **Caching**: Uses in-memory `NullRedisClient` or local mocking (no Redis required)
-- **Speed**: Fast execution
-- **Use Case**: CI/CD, development validation, regression testing
-
-### 2. Example Files (`*.examples.js`)
-- **Purpose**: Non-deterministic integration tests with real LLM calls
-- **Reliability**: May fail due to LLM response variability
-- **LLM Usage**: Makes actual API calls to language models
-- **Caching**: Uses Redis for response caching (when available)
-- **Speed**: Slower due to network calls (mitigated by caching)
-- **Use Case**: Manual testing, demonstrating real-world usage, validating LLM integration
-
-## Environment Configuration
-
-### Spec Tests
-```bash
-npm test                    # Runs spec tests with mocked responses
-```
-
-### Example Tests
-```bash
-npm run examples                # Runs example tests with real LLM calls
-EXAMPLES=true npm run examples  # Automatically set, enables Redis caching
-```
-
-### Caching Control
-```bash
-# Disable caching for all LLM calls (forces fresh API calls)
-DISABLE_CACHE=true npm run examples
-
-# Enable caching (default behavior when Redis is available)
-npm run examples
-```
-
-## Caching System
-
-### Redis Caching for Examples
-- Example tests use Redis to cache LLM responses based on prompt content
-- Cached responses reduce API costs and improve test speed
-- Falls back to in-memory caching if Redis is unavailable
-
-### Cache Behavior
-- **Cache Hit**: Returns cached response instantly
-- **Cache Miss**: Makes LLM API call and caches the response
-- **TTL**: Cached responses expire after 365 days (configurable via `CHATGPT_CACHE_TTL`)
-- **Fallback**: Gracefully handles Redis connection failures
-
-## Development Workflow
-
-### Adding New Verblets or Chains
-
-When creating a new verblet or chain, you should add both types of tests:
-
-#### 1. Create Spec File (`index.spec.js`)
-```javascript
-import { describe, expect, it } from 'vitest';
-import myVerblet from './index.js';
-
-const examples = [
-  {
-    inputs: { text: 'test input' },
-    want: { result: 'expected output' },
-  },
-];
-
-describe('My Verblet', () => {
-  examples.forEach((example) => {
-    it(example.inputs.text, async () => {
-      const result = await myVerblet(example.inputs.text);
-      expect(result).toStrictEqual(example.want.result);
-    });
-  });
-});
-```
-
-#### 2. Create Example File (`index.examples.js`)
-```javascript
-import { describe, expect, it } from 'vitest';
-import myVerblet from './index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-describe('My Verblet Examples', () => {
-  it(
-    'processes real input',
-    async () => {
-      const result = await myVerblet('What is the capital of France?');
-      expect(typeof result).toBe('string');
-      expect(result.length).toBeGreaterThan(0);
-    },
-    longTestTimeout
-  );
-});
-```

package/docker-compose.yml

@@ -1,7 +0,0 @@
-version: '3.8'
-
-services:
-  redis:
-    image: 'redis:latest'
-    ports:
-      - '6379:6379'

package/eslint.config.js

@@ -1,80 +0,0 @@
-import js from '@eslint/js';
-import prettierConfig from 'eslint-config-prettier';
-import prettierPlugin from 'eslint-plugin-prettier';
-
-export default [
-  js.configs.recommended,
-  {
-    files: ['src/**/*.js'],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: 'module',
-      globals: {
-        console: 'readonly',
-        process: 'readonly',
-        Buffer: 'readonly',
-        __dirname: 'readonly',
-        __filename: 'readonly',
-        URL: 'readonly',
-        AbortController: 'readonly',
-        fetch: 'readonly',
-        setTimeout: 'readonly',
-        clearTimeout: 'readonly',
-        setInterval: 'readonly',
-        clearInterval: 'readonly',
-        // Vitest
-        beforeEach: 'readonly',
-        afterEach: 'readonly',
-        describe: 'readonly',
-        it: 'readonly',
-        expect: 'readonly',
-        vi: 'readonly',
-      },
-    },
-    linterOptions: {
-      reportUnusedDisableDirectives: false,
-    },
-    plugins: {
-      prettier: prettierPlugin,
-    },
-    rules: {
-      'prettier/prettier': 'error',
-      
-      // TODO: Remove console statements and replace with proper logging
-      'no-console': 'off',
-      
-      // TODO: Refactor await-in-loop patterns to use Promise.all()
-      'no-await-in-loop': 'off',
-
-      // Customize recommended rules
-      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-
-      // Additional quality rules not in recommended
-      'require-await': 'error',
-      'prefer-arrow-callback': 'error',
-      'prefer-template': 'error',
-      'object-shorthand': 'error',
-      'array-callback-return': 'error',
-
-      // Syntax restrictions
-      'no-restricted-syntax': [
-        'error',
-        {
-          selector: 'ForInStatement',
-          message: 'Use Object.{keys,values,entries} instead of for..in',
-        },
-        {
-          selector: 'WithStatement',
-          message: '`with` is not allowed',
-        },
-      ],
-    },
-  },
-  {
-    files: ['**/*.spec.js', '**/*.test.js'],
-    rules: {
-      'require-await': 'off', // Test functions often don't need await
-    },
-  },
-  prettierConfig,
-]; 

package/scripts/clear-redis.js

@@ -1,74 +0,0 @@
-#!/usr/bin/env node
-
-import { getClient as getRedis } from '../src/services/redis/index.js';
-
-async function clearRedisKeys() {
-  let redis = null;
-  
-  try {
-    console.log('🔄 Connecting to Redis...');
-    redis = await getRedis();
-    
-    // Check if this is the NullRedisClient (in-memory fallback)
-    if (redis.store !== undefined) {
-      // This is the in-memory client
-      const keyCount = Object.keys(redis.store).length;
-      if (keyCount === 0) {
-        console.log('✅ In-memory cache is already empty - no keys to clear');
-        return;
-      }
-      
-      console.log(`🗑️  Found ${keyCount} keys in in-memory cache to clear`);
-      redis.store = {};
-      console.log(`✅ Successfully cleared ${keyCount} in-memory cache keys`);
-      console.log('🧹 In-memory cache has been cleared - tests can now run with fresh responses');
-      return;
-    }
-    
-    // This is the SafeRedisClient wrapper - access underlying Redis client
-    const underlyingClient = redis.redisClient;
-    if (!underlyingClient) {
-      console.log('⚠️  No underlying Redis client found - using fallback method');
-      return;
-    }
-    
-    // Get count of keys before clearing
-    const keys = await underlyingClient.keys('*');
-    const keyCount = keys.length;
-    
-    if (keyCount === 0) {
-      console.log('✅ Redis is already empty - no keys to clear');
-      return;
-    }
-    
-    console.log(`🗑️  Found ${keyCount} keys to clear`);
-    
-    // Use FLUSHDB to clear all keys in the current database
-    // This is more efficient and reliable than deleting individual keys
-    await underlyingClient.flushDb();
-    
-    console.log(`✅ Successfully cleared all ${keyCount} Redis keys`);
-    console.log('🧹 Redis cache has been cleared - tests can now run with fresh responses');
-    
-  } catch (error) {
-    if (error.message.includes('ECONNREFUSED') || error.message.includes('connection')) {
-      console.log('⚠️  Redis is not running or not accessible - nothing to clear');
-      console.log('   This is normal if you\'re using the in-memory cache fallback');
-    } else {
-      console.error('❌ Error clearing Redis keys:', error.message);
-      process.exit(1);
-    }
-  } finally {
-    if (redis && typeof redis.disconnect === 'function') {
-      try {
-        await redis.disconnect();
-        console.log('🔌 Disconnected from Redis');
-      } catch (disconnectError) {
-        // Ignore disconnect errors
-      }
-    }
-  }
-}
-
-// Run the script
-clearRedisKeys(); 

package/scripts/generate-chain/index.js

@@ -1,111 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import {
-  camelCase,
-  paramCase,
-  sentenceCase,
-} from 'change-case';
-
-const chainName = process.argv[2];
-
-if (!chainName) {
-  console.error('Please specify a chain name.');
-  process.exit(1);
-}
-
-const chainDir = `./src/chains/${paramCase(chainName)}`;
-const indexFile = `${chainDir}/index.js`;
-const testFile = `${chainDir}/index.spec.js`;
-const exampleFile = `${chainDir}/index.examples.js`;
-
-const createFileIfNotExists = (filePath, fileContent, fileType) => {
-  if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, fileContent);
-    console.error(`Created new ${fileType} file: ${filePath}`);
-  } else {
-    console.error(`Creating ${fileType} file [skipped]: '${filePath}' exists`);
-  }
-}
-
-// Check if the chain directory already exists
-if (!fs.existsSync(chainDir)) {
-  // Create the chain directory
-  fs.mkdirSync(chainDir, { recursive: true });
-}
-
-const indexContent = `
-export default async (text) => {
-  // TODO: Implement ${paramCase(chainName)} chain
-};
-`;
-createFileIfNotExists(indexFile, indexContent, 'module file');
-
-const testContent = `import { describe, expect, it, vi } from 'vitest';
-
-import ${camelCase(chainName)} from './index.js';
-
-vi.mock('../../lib/chatgpt/index.js', () => ({
-  default: vi.fn().mockImplementation((text) => {
-    if (/prompt text to match/.test(text)) {
-      return 'True';
-    } else {
-      return 'undefined';
-    }
-  }),
-}));
-
-const examples = [
-  {
-    name: 'Basic usage',
-    inputs: { text: 'test' },
-    want: { result: true }
-  }
-];
-
-describe('${sentenceCase(chainName)} chain', () => {
-  examples.forEach((example) => {
-    it(example.name, async () => {
-      const result = await ${camelCase(chainName)}(example.inputs.text);
-
-      if (example.want.typeOfResult) {
-        expect(typeof result)
-          .toStrictEqual(example.want.typeOfResult);
-      }
-    });
-  });
-});
-`;
-createFileIfNotExists(testFile, testContent, 'test');
-
-const exampleContent = `import { describe, expect, it, vi } from 'vitest';
-
-import ${camelCase(chainName)} from './index.js';
-
-const examples = [
-  {
-    inputs: { text: 'test' },
-    want: { result: true }
-  }
-];
-
-describe('${sentenceCase(chainName)} chain', () => {
-  examples.forEach((example) => {
-    it(example.inputs.text, async () => {
-      const result = await ${camelCase(chainName)}(example.inputs.text)
-
-      if (example.want.typeOfResult) {
-        expect(typeof result)
-          .toStrictEqual(example.want.typeOfResult);
-      }
-
-      if (example.want.result) {
-        expect(result)
-          .toStrictEqual(example.want.result);
-      }
-    });
-  });
-});
-`;
-createFileIfNotExists(exampleFile, exampleContent, 'example');
-
-console.error(`Created new chain: ${chainName}`);

package/scripts/generate-lib/index.js

@@ -1,68 +0,0 @@
-import fs from 'node:fs';
-import {
-  camelCase,
-  paramCase,
-  sentenceCase,
-} from 'change-case';
-
-const libName = process.argv[2];
-
-if (!libName) {
-  console.error('Please specify a library name.');
-  process.exit(1);
-}
-
-const libDir = `./src/lib/${paramCase(libName)}`;
-const indexFile = `${libDir}/index.js`;
-const testFile = `${libDir}/index.spec.js`;
-
-const createFileIfNotExists = (filePath, fileContent, fileType) => {
-  if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, fileContent);
-    console.error(`Created new ${fileType} file: ${filePath}`);
-  } else {
-    console.error(`Creating ${fileType} file [skipped]: '${filePath}' exists`);
-  }
-}
-
-// Check if the lib directory already exists
-if (!fs.existsSync(libDir)) {
-  // Create the lib directory
-  fs.mkdirSync(libDir, { recursive: true });
-}
-
-const indexContent = `
-export default async (text) => {
-  // TODO: Implement ${paramCase(libName)} lib
-};
-`;
-createFileIfNotExists(indexFile, indexContent, 'module file');
-
-const testContent = `import { describe, expect, it, vi } from 'vitest';
-
-import ${camelCase(libName)} from './index.js';
-
-const examples = [
-  {
-    name: 'Basic usage',
-    inputs: { text: 'test' },
-    want: { result: true }
-  }
-];
-
-describe('${sentenceCase(libName)} lib', () => {
-  examples.forEach((example) => {
-    it(example.name, async () => {
-      const result = await ${camelCase(libName)}(example.inputs.text);
-
-      if (example.want.typeOfResult) {
-        expect(typeof result)
-          .toStrictEqual(example.want.typeOfResult);
-      }
-    });
-  });
-});
-`;
-createFileIfNotExists(testFile, testContent, 'test');
-
-console.error(`Created new lib: ${libName}`);

package/scripts/generate-test/index.js

@@ -1,137 +0,0 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import parseJSParts from '../../src/lib/parse-js-parts/index.js';
-import
-chatGPT,
-{
-  getRedis,
-  SummaryMap
-} from '../../src/index.js';
-import modelService from '../../src/services/llm-model/index.js';
-import { Command } from 'commander';
-
-const program = new Command();
-program
-  .argument('<modulePath>', 'Module to test')
-  .argument('[functionName]', 'Specific function to test')
-  .option('-p, --privacy', 'Use privacy model if configured')
-  .option('-m, --model <modelName>', 'Specify model name to use');
-
-program.parse(process.argv);
-
-const options = program.opts();
-const [modulePath, functionName] = program.args;
-
-if (options.privacy) {
-  try {
-    modelService.setGlobalOverride('modelName', 'privacy');
-  } catch (err) {
-    console.error(`Privacy model error: ${err.message}`);
-  }
-}
-if (options.model) {
-  try {
-    modelService.setGlobalOverride('modelName', options.model);
-  } catch (err) {
-    console.error(`Model override error: ${err.message}`);
-  }
-}
-
-if (!modulePath) {
-  console.error('Please specify a module to test.');
-  process.exit(1);
-}
-
-try {
-  await fs.stat(modulePath);
-} catch (err) {
-  console.error(`Module not found at: ${modulePath}`);
-  process.exit(1);
-}
-
-const moduleDir = path.dirname(modulePath);
-const moduleName = path.basename(moduleDir);
-const testFile = path.join(moduleDir, `${moduleName}.spec.js`);
-
-const examplePath1 = './src/lib/parse-js-parts/parse-js-parts.spec.js';
-
-try {
-  await fs.stat(examplePath1);
-} catch (error) {
-  console.error(`Generate test [error]: ${error.message}`);
-  process.exit(1);
-}
-
-const generatePrompt = ({ moduleFile, modulePath, examples=[] }) => {
-  const examplesJoined = examples.map((example) => `<example>${example}</example>`).join('\n');
-
-  let prompt = `Generate a test file for module shown below.
-
-Examples to inform the results:
-${examplesJoined}
-
-<module-to-test>${moduleFile}</module-to-test>`;
-
-  return prompt;
-}
-
-async function generateTestFile(modulePath) {
-  const moduleFile = await fs.readFile(modulePath, 'utf-8');
-
-  const example1 = (await fs.readFile(examplePath1, 'utf-8'));
-  // const example2 = await fs.readFile(examplePath2, 'utf-8');
-
-  const fixes = [];
-  if (functionName) {
-    fixes.push('For the function "${functionName}", keep as much of the code as you can.');
-  }
-
-  let functionNameDisplay = '';
-  if (functionName) {
-    functionNameDisplay = `, only for "${functionName}"`
-  }
-
-  let moduleFileSliced = moduleFile;
-  if (functionName) {
-    const results = parseJSParts(modulePath, moduleFile);
-
-    const funcs = Object.keys(results.functionsMap);
-    const funcFound = funcs.find(f => (new RegExp(`${functionName}$`)).test(f));
-    const funcDefFound = results.functionsMap?.[funcFound];
-    if (funcDefFound) {
-      moduleFileSliced = moduleFile.slice(funcDefFound.start, funcDefFound.end);
-    }
-  }
-
-  const argsMap = new SummaryMap({ promptText: generatePrompt.toString() });
-
-  argsMap.set('functionName', { value: functionName });
-  argsMap.set('modulePath', { value: modulePath });
-  argsMap.set('moduleFile', {
-    value: moduleFileSliced,
-    weight: 1,
-    type: 'code',
-    fixes,
-  })
-  argsMap.set('examples.0', {
-    value: example1,
-    weight: 1,
-    type: 'code',
-    fixes: ['Keep at least one of the example definitions in the example array'],
-  })
-
-  const prompt = await generatePrompt(await argsMap.pavedSummaryResult());
-
-  console.error(prompt)
-
-  const response = await chatGPT(prompt);
-
-  // use standard shell IO to apply the generated code
-  console.error(response);
-}
-
-// Example usage:
-await generateTestFile(modulePath);
-
-await (await getRedis()).disconnect();

package/scripts/generate-verblet/README.md

@@ -1,17 +0,0 @@
-# Verblet Generator
-
-This is a Node script that generates a new "verblet" module and test file in a specific directory structure.
-
-## Usage
-
-To use this script, run the following command:
-
-```
-npm run script -- generate-verblet [verblet-name]
-```
-
-Replace `[verblet-name]` with the name of your new verblet. The script will create a new directory called `./src/verblets/[verblet-name]` and generate an `index.js` file and a test file inside that directory.
-
-The generated `index.js` file exports a single default async function that you can implement to define the behavior of the verblet.
-
-The generated test file is located at `./src/verblets/[verblet-name]/[verblet-name].spec.js`. It contains a sample test that you can modify to test your verblet implementation.