Transparency-Logic-Time-Machine-Bots-

The Grand United Fields of Theories

Overview

This project includes comprehensive quality and hardening features:

• Config Validation: Type-safe configuration with Zod validation
• Telemetry: Optional OpenTelemetry integration (no vendor lock-in)
• Security Scanning: Trivy vulnerability scanning and SBOM generation
• Pre-commit Hooks: Automatic linting and formatting
• Dependency Management: Renovate for automated updates

Installation

Base Installation

Install core dependencies only:

npm install

Optional Heavy Dependencies

Heavy AI/ML and vector database dependencies are optional. Install only what you need:

# Install all optional dependencies
npm install --include=optional

# Or install specific optional dependencies:
npm install @huggingface/transformers    # HuggingFace Transformers
npm install pinecone-client               # Pinecone vector database
npm install weaviate-ts-client            # Weaviate vector database
npm install chromadb                      # Chroma vector database
npm install @anchordotdev/anchor          # Anchor.dev

Why optional? These packages are large and not needed for basic functionality. Install only what your use case requires.

Configuration

Configuration Validation

The project uses Zod for runtime configuration validation. Configuration is loaded from environment variables with type checking and validation.

Configuration Schema:

• APP_NAME: Application name (default: transparency-logic-time-machine-bots)
• NODE_ENV or APP_ENV: Environment (development|staging|production)
• PORT: Server port (default: 3000)
• LOG_LEVEL: Logging level (debug|info|warn|error, default: info)
• TELEMETRY_*: Optional telemetry settings
• AI_*: Optional AI/ML settings
• VECTOR_DB_*: Optional vector database settings

Example:

# Copy example environment file
cp .env.example .env

# Edit configuration
nano .env

Validate Configuration:

# Build the project first
npm run build

# Run config validation smoke test
npm run validate:config

The validation performs no network calls - only local parsing and validation.

Telemetry

OpenTelemetry Integration

Optional OpenTelemetry integration with no vendor lock-in. Uses standard OpenTelemetry APIs compatible with any OTLP-compatible backend (Jaeger, Zipkin, Datadog, New Relic, etc.).

Enable Telemetry:

# Set in .env file
TELEMETRY_ENABLED=true
TELEMETRY_SERVICE_NAME=my-service
TELEMETRY_ENDPOINT=http://localhost:4318  # Optional - OTLP endpoint
TELEMETRY_SAMPLE_RATE=0.1                 # Sample 10% of traces

Features:

• Automatic instrumentation via OpenTelemetry auto-instrumentations
• Distributed tracing with standard OpenTelemetry APIs
• Structured logging with context
• No vendor lock-in - use any OTLP-compatible backend

Usage:

import { getTracer, createLogger } from './telemetry';

const logger = createLogger('my-module');
const tracer = getTracer('my-module');

logger.info('Processing request', { userId: '123' });

const span = tracer.startSpan('my-operation');
// ... your code ...
span.end();

Development

Building

npm run build

Linting and Formatting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Check formatting
npm run format:check

# Fix formatting
npm run format

Pre-commit Hooks

Pre-commit hooks are automatically installed via husky. They will:

1. Run lint-staged to format and lint changed files
2. Run config validation smoke test (if built)

Manual setup (if needed):

# Install husky hooks
npm run prepare

Testing

npm test

Security

Vulnerability Scanning

The project uses Trivy for security scanning. Scans run automatically on:

• Every push to master/main
• Every pull request
• Weekly schedule (Monday 00:00 UTC)
• Manual workflow dispatch

View Security Results:

• GitHub Security tab → Code scanning alerts
• Workflow runs → Security Scan workflow

Run Locally:

# Install Trivy (macOS)
brew install aquasecurity/trivy/trivy

# Run scan
trivy fs .

SBOM Generation

Software Bill of Materials (SBOM) is generated using Syft in both SPDX and CycloneDX formats.

Download SBOM:

1. Go to Actions → Security Scan workflow
2. Click on a workflow run
3. Download "sbom-files" artifact

Generate Locally:

# Install Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

# Generate SBOM
syft packages . -o spdx-json=sbom.spdx.json -o cyclonedx-json=sbom.cyclonedx.json

Dependency Management

Renovate

This project uses Renovate for automated dependency updates.

Configuration:

• Schedule: Updates run before 5am on Monday (UTC)
• Heavy Dependencies: AI/ML packages update monthly to reduce churn
• Auto-merge: Patch updates for dev dependencies
• Grouping: Related packages updated together
• Security Alerts: Enabled with "security" label

Renovate Dashboard: Check Issues tab for the Renovate Dependency Dashboard

Configuration File: renovate.json

Service Integrations

Full Stack Toolkit

This project includes a standardized integration framework for cross-platform services.

Supported Services:

• OpenAI - AI/ML capabilities
• ManyChat - Chatbot automation
• BotBuilders - Bot development platform
• Moltbook - Service integration
• Moltbot - Service integration
• OpenClaw - Service integration
• GitHub API - Extended GitHub operations
• Webhooks - Generic webhook notifications

Configuration:

1. Copy the example configuration:

   cp config/services.example.json config/services.json

2. Set environment variables or GitHub secrets for the services you want to use:

   export OPENAI_API_KEY=your-key-here
   export MANYCHAT_API_KEY=your-key-here
   # ... etc

3. For GitHub Actions: Add secrets in Repository Settings → Secrets and variables → Actions

Available Secrets:

• OPENAI_API_KEY - OpenAI API key
• MANYCHAT_API_KEY - ManyChat API key
• BOTBUILDERS_API_KEY - BotBuilders API key
• MOLTBOOK_API_KEY - Moltbook API key
• MOLTBOT_API_KEY - Moltbot API key
• OPENCLAW_API_KEY - OpenClaw API key
• GITHUB_PAT - GitHub Personal Access Token (for extended API access)
• WEBHOOK_URL - Generic webhook endpoint URL
• SERVICE_BASE_URL_OPENCLAW - Custom OpenClaw base URL (optional)
• SERVICE_BASE_URL_* - Custom base URLs for other services (optional)

Security:

⚠️ NEVER commit config/services.json with real secrets - it's already in .gitignore

✓ Always use environment variables or GitHub secrets for credentials

✓ See config/services.example.json for detailed documentation and best practices

CI/CD

Workflows

CI Workflow (.github/workflows/blank.yml):

• Linting and formatting checks
• TypeScript compilation
• Config validation smoke tests
• Tests

Security Workflow (.github/workflows/security.yml):

• Trivy vulnerability scanning
• SBOM generation with Syft
• Results uploaded to GitHub Security tab

Integration Checks Workflow (.github/workflows/integrations.yml):

• Manual trigger via workflow_dispatch
• Automatic trigger on push to main
• Detects presence of service API keys (never prints secret values)
• Placeholder connectivity checks for: OpenAI, ManyChat, BotBuilders, Moltbook, Moltbot, OpenClaw, GitHub, Webhooks
• Dry-run oriented (safe for all environments)
• No external dependencies (pure bash/curl)

Project Structure

.
├── src/
│   ├── config/          # Configuration validation module
│   │   ├── index.ts     # Config schema and loader
│   │   └── validator.ts # Smoke test script
│   ├── telemetry/       # OpenTelemetry integration
│   │   └── index.ts     # Tracer and logger setup
│   └── index.ts         # Main entry point
├── .github/
│   └── workflows/       # GitHub Actions workflows
├── .husky/              # Git hooks
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── renovate.json        # Renovate configuration
└── .env.example         # Example environment variables

License

MIT