tasq/node_modules/agentdb/scripts

AgentDB Scripts Directory

This directory contains build, validation, and deployment scripts for AgentDB v2.

Build Scripts

Browser Builds

build-browser.js

Purpose: Original browser bundle builder Usage: node scripts/build-browser.js Output: dist/agentdb.browser.js Features:

• Basic SQL.js WASM integration
• Single-file browser bundle
• CDN-ready output

build-browser-v2.js

Purpose: Enhanced v2 browser bundle with advanced features Usage: node scripts/build-browser-v2.js Output: dist/agentdb.browser.v2.js Features:

• Multi-backend support (SQL.js/IndexedDB auto-detection)
• GNN optimization integration
• IndexedDB persistence
• Cross-tab synchronization
• 100% v1 API backward compatibility
• Enhanced error handling

Recommended: Use this for new projects requiring browser support.

build-browser-advanced.cjs

Purpose: Advanced browser features build Usage: node scripts/build-browser-advanced.cjs Features:

• Advanced WASM optimization
• Progressive loading
• Service worker integration
• Memory management enhancements

Dependencies

postinstall.cjs

Purpose: Post-installation setup and verification Auto-runs: After npm install Tasks:

• Validates environment
• Checks native dependencies (better-sqlite3)
• Sets up development environment
• Verifies WASM files

Validation Scripts

comprehensive-review.ts

Purpose: Complete v2 feature validation and performance testing Usage: tsx scripts/comprehensive-review.ts Tests:

• @ruvector/core integration
• @ruvector/gnn integration
• ReasoningBank functionality
• All v2 controllers (HNSW, QUIC, etc.)
• Backend performance comparison
• Memory usage analysis
• Optimization opportunities

Output: Comprehensive test report with metrics

validate-security-fixes.ts

Purpose: Security validation and audit Usage: tsx scripts/validate-security-fixes.ts Checks:

• SQL injection prevention
• Input sanitization
• Path traversal protection
• Dependency vulnerabilities
• Code signing verification

verify-bundle.js

Purpose: Bundle integrity verification Usage: node scripts/verify-bundle.js Validates:

• Bundle size limits
• Export completeness
• API surface consistency
• WASM file integrity

verify-core-tools-6-10.sh

Purpose: Core tools validation (tools 6-10) Usage: bash scripts/verify-core-tools-6-10.sh Tests:

• Tool 6: Batch insert operations
• Tool 7: Hybrid search
• Tool 8: QUIC synchronization
• Tool 9: Learning plugins
• Tool 10: Performance benchmarks

Release Scripts

npm-release.sh

Purpose: Automated NPM release workflow Usage: bash scripts/npm-release.sh [version] Process:

1. Version bump (semver)
2. Changelog generation
3. Build verification
4. Test suite execution
5. Bundle validation
6. NPM publish
7. Git tag creation

Requirements:

• NPM authentication
• Git repository
• Clean working tree

pre-release-validation.sh

Purpose: Pre-release quality gate Usage: bash scripts/pre-release-validation.sh Validates:

• All tests passing
• No TypeScript errors
• Bundle integrity
• Documentation accuracy
• Security audit clean
• Performance benchmarks met

Testing Scripts

docker-test.sh

Purpose: Docker environment testing Usage: bash scripts/docker-test.sh Tests:

• Installation in clean environment
• Runtime dependencies
• Cross-platform compatibility
• Network isolation scenarios

docker-validation.sh

Purpose: Comprehensive Docker validation suite Usage: bash scripts/docker-validation.sh Includes:

• Multi-stage build verification
• Container security scan
• Resource usage monitoring
• Integration test suite

AgentDB Version

Current Version: 1.6.1 Target: v2.0.0 with full backward compatibility

All scripts are designed to work with:

• Node.js: >=18.0.0
• TypeScript: ^5.7.2
• Better-sqlite3: ^11.8.1 (optional)
• @ruvector/core: ^0.1.15
• @ruvector/gnn: ^0.1.15

Development Workflow

1. Local Development

npm run build          # Full build pipeline
npm run dev           # Development mode with tsx
npm test              # Run test suite

2. Browser Testing

npm run build:browser  # Build browser bundle
npm run test:browser   # Test browser bundle
npm run verify:bundle  # Verify bundle integrity

3. Pre-Release Validation

bash scripts/pre-release-validation.sh
tsx scripts/comprehensive-review.ts
tsx scripts/validate-security-fixes.ts

4. Release

bash scripts/npm-release.sh patch  # Patch release
bash scripts/npm-release.sh minor  # Minor release
bash scripts/npm-release.sh major  # Major release

Script Dependencies

Required Global Tools

• node (>=18.0.0)
• npm (>=9.0.0)
• bash (>=4.0)
• tsx (for TypeScript scripts)
• docker (for container tests)

Package Scripts Integration

Scripts integrate with package.json scripts:

{
  "scripts": {
    "build": "npm run build:ts && npm run copy:schemas && npm run build:browser",
    "build:browser": "node scripts/build-browser.js",
    "postinstall": "node scripts/postinstall.cjs || true",
    "verify:bundle": "node scripts/verify-bundle.js",
    "docker:test": "bash scripts/docker-test.sh"
  }
}

Troubleshooting

Build Failures

Problem: Browser bundle build fails Solution:

# Clear dist and rebuild
rm -rf dist
npm run build

Problem: WASM files not loading Solution:

# Re-download dependencies
rm -rf node_modules
npm install

Validation Failures

Problem: Security validation fails Solution:

npm audit fix
tsx scripts/validate-security-fixes.ts

Problem: Bundle size exceeded Solution:

# Check bundle analysis
npm run verify:bundle
# Consider code splitting or lazy loading

Release Issues

Problem: NPM publish fails Solution:

# Verify authentication
npm whoami
npm login

# Check version
npm version patch --no-git-tag-version

Best Practices

1. Always run validation before releases:

   bash scripts/pre-release-validation.sh
   

2. Test browser builds locally:

   npm run test:browser
   

3. Keep dependencies updated:

   npm outdated
   npm update
   

4. Run security audits regularly:

   tsx scripts/validate-security-fixes.ts
   

5. Verify Docker compatibility:

   bash scripts/docker-test.sh
   

Contributing

When adding new scripts:

1. Add executable permissions: chmod +x script-name.sh
2. Include shebang line: #!/usr/bin/env node or #!/usr/bin/env bash
3. Add comprehensive error handling
4. Document in this README
5. Add to package.json scripts if appropriate
6. Include validation tests

Support

For issues with scripts:

• Check logs in logs/ directory
• Review error messages carefully
• Verify Node.js/npm versions
• Check GitHub Issues: https://github.com/ruvnet/agentic-flow/issues

---

Last Updated: 2025-11-29 AgentDB Version: 1.6.1 → 2.0.0