tasq/node_modules/agentic-flow/validation/docker/README.md

Docker Validation for ReasoningBank

This directory contains Docker-based validation scripts to test agentic-flow package in clean, isolated environments.

Purpose

Validates that agentic-flow works correctly when installed via npm/npx in a fresh Node.js environment, testing:

1. Package Installation - npm install works correctly
2. Backend Selector - Environment detection functions properly
3. Node.js Backend - SQLite backend initializes and works
4. WASM Backend - WASM module loads and functions in Node.js
5. Package Exports - All export paths resolve correctly

Quick Start

Test Local Build

# From agentic-flow root directory

# 1. Build the package
npm run build

# 2. Create package tarball
npm pack

# 3. Run Docker validation
cd validation/docker
docker build -f Dockerfile.reasoningbank-local -t agentic-flow-test:local ../..
docker run --rm agentic-flow-test:local

Test Published Version

# Test latest published version from npm
docker build -f Dockerfile.reasoningbank-test -t agentic-flow-test:latest ../..
docker run --rm agentic-flow-test:latest

# Or use docker-compose
docker-compose up reasoningbank-test-latest

Files

File	Purpose
Dockerfile.reasoningbank-test	Tests published npm package
Dockerfile.reasoningbank-local	Tests local build (npm pack)
test-reasoningbank-npx.mjs	Validation test suite
docker-compose.yml	Orchestrates multiple test scenarios
README.md	This file

Test Suite

The validation script (test-reasoningbank-npx.mjs) runs:

Test 1: Package Installation

• Initializes package.json
• Installs agentic-flow via npm
• Verifies installation success

Test 2: Backend Selector

• Imports backend-selector module
• Tests environment detection (expects 'nodejs')
• Validates backend info structure
• Checks environment validation

Test 3: Node.js Backend (SQLite)

• Creates ReasoningBank with optimal backend
• Verifies Node.js backend selected
• Checks db module is present
• Tests database initialization

Test 4: WASM Backend

• Imports WASM adapter
• Creates WASM ReasoningBank instance
• Stores test pattern
• Performs category search
• Runs semantic similarity search
• Validates similarity scores
• Checks stats reporting

Test 5: Package Exports

• Tests main export (agentic-flow)
• Tests reasoningbank export (conditional)
• Tests backend-selector export
• Tests wasm-adapter export

Expected Output

🐳 Docker Validation: agentic-flow ReasoningBank

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Created test directory: /test/validation-workspace

📦 Test 1: Package Installation via npm

   Installing agentic-flow@latest...
✅ Package installation
   Installed agentic-flow@1.5.13

🔍 Test 2: Backend Selector Environment Detection

✅ Backend selector import
   Detected: nodejs

✅ Environment detection
   Expected nodejs, got nodejs

💾 Test 3: Node.js Backend (SQLite)

✅ Node.js backend initialization
   SQLite backend loaded

✅ Node.js backend detection
   db module present

⚡ Test 4: WASM Backend (In-Memory)

✅ WASM backend initialization
   WASM module loaded

✅ WASM pattern storage
   In-memory storage works

✅ WASM semantic search
   Similarity matching works

✅ WASM similarity scoring
   Score: 0.5401

📦 Test 5: Package Exports

✅ Package exports
   All import paths valid

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Tests: 10
✅ Passed: 10
❌ Failed: 0
⏱️  Duration: 45.23s

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎉 All tests passed! Package is working correctly.

Troubleshooting

Test Failures

If tests fail, check:

1. Package installation fails

   • Verify network connectivity
   • Check npm registry is accessible
   • Try with --registry https://registry.npmjs.org

2. Backend selector fails

   • Check package.json exports field
   • Verify conditional exports syntax
   • Test with node --experimental-modules

3. WASM backend fails

   • Ensure --experimental-wasm-modules flag is set
   • Check WASM binary is included in dist/
   • Verify wasm-pack build completed

4. SQLite backend fails

   • Check better-sqlite3 is in dependencies
   • Verify native module compilation
   • Test on matching Node.js version

Local Testing

To test locally without Docker:

cd /tmp
mkdir reasoningbank-test && cd reasoningbank-test
npm init -y
npm install agentic-flow@latest

# Run individual tests
node --experimental-wasm-modules <<EOF
import { getRecommendedBackend } from 'agentic-flow/reasoningbank/backend-selector';
console.log('Backend:', getRecommendedBackend());
EOF

CI/CD Integration

Add to GitHub Actions:

- name: Validate agentic-flow in Docker
  run: |
    cd validation/docker
    docker build -f Dockerfile.reasoningbank-local -t test ../..
    docker run --rm test    

Performance Benchmarks

Expected performance in Docker:

Operation	Time
Package install	15-30s
Backend detection	<100ms
WASM initialization	50-100ms
Pattern storage	1-5ms
Semantic search	50-100ms

Environment Details

• Base Image: node:20-slim
• Node.js Version: 20.x LTS
• Architecture: linux/amd64
• Dependencies: git, curl

Support

If validation fails:

1. Check the REASONINGBANK_BACKENDS.md guide
2. Review IMPLEMENTATION_SUMMARY.md
3. Open an issue at https://github.com/ruvnet/agentic-flow/issues