Copilot-LD – Development Guide

Development Guide

This guide focuses on local development, testing, and validation workflows for Copilot-LD. For initial setup and configuration, see the Configuration Guide. For knowledge base processing, see the Processing Guide.

Prerequisites

Complete the initial setup steps:

Configuration Guide - Environment setup and GitHub authentication
Processing Guide - Knowledge base processing (if using custom content)

Development Workflow

By default all services run in development mode with debug logging enabled.

# Launch all services in development mode
npm run dev:start

# Stop development environment
npm run dev:stop

# Restart development environment
npm run dev:restart

Testing and Validation

Run various testing and validation checks:

# Execute all tests
npm test

# Execute tests in watch mode for TDD
npm run test:watch

# Run performance benchmarks
npm run perf

# Run all quality checks
npm run check

# Auto-fix issues where possible
npm run check:fix

# Individual checks
npm run lint           # ESLint code analysis
npm run format         # Prettier formatting check
npm run spellcheck     # Spell check documentation

Security Auditing

Check for security vulnerabilities:

npm run security

Development Scripts

The scripts/ directory contains utilities for development and testing:

Interactive Testing

# Interactive chat with the system
node scripts/chat.js
> What are Docker security best practices?
> How do I implement rolling updates in Kubernetes?

# Semantic search testing
node scripts/search.js
> docker security
> kubernetes deployment

Scripted Testing

# Pipe input for automated testing
echo "Tell me about container security" | node scripts/chat.js

# Search with CLI flags for precise testing
echo "docker" | node scripts/search.js --limit 10 --threshold 0.25

# Test descriptor-based search
echo "kubernetes deployment" | node scripts/search.js --index descriptor --limit 5

System Validation Scripts

# Test vector embeddings and similarity
node scripts/cosine.js "first text" "second text"

# Validate model configurations
node scripts/models.js

# Test embedding generation
echo "sample text" | node scripts/embed.js

Development Utilities

# Generate SSL certificates for HTTPS development
node scripts/cert.js

# Generate service authentication secrets
node scripts/secret.js

# GitHub token setup and validation
node scripts/token.js

Code Generation Workflow

For details about Protocol Buffer compilation and type generation, see the Code Generation section in the Architecture Guide.

# Generate all code from proto definitions
mkdir generated
npm run codegen

npm run codegen:type      # Type definitions only
npm run codegen:client    # Client stubs only
npm run codegen:service   # Service bases only

Web Interface Testing

Access the development interfaces:

Web Extension: http://localhost:3000/web
Copilot Extension: http://localhost:3001/copilot
Documentation Server: npm run docs serves on http://localhost:8080

Development Troubleshooting

Service Issues

Port conflicts: Ensure ports 3000–3007 are available
Service startup failures: Check config/.env configuration
gRPC connection errors: Verify service networking configuration
Authentication failures: Validate SERVICE_SECRET and GITHUB_TOKEN

Knowledge Base Issues

Empty responses: Verify vector indices exist in data/vectors/
Processing errors: Check data/resources/ for processed content
Missing tools: Ensure npm run codegen completed successfully

Development Validation

Quick validation of your development environment:

# Test basic system functionality
echo "hello" | node scripts/chat.js

# Verify code generation
ls generated/types/
ls generated/services/

# Check processed knowledge base
ls data/resources/ | head -5
ls data/vectors/

# Validate service configuration
npm test -- --grep="Config"

Next Steps

Configuration Guide - Environment setup and authentication
Processing Guide - Knowledge base processing and tool setup
Architecture Guide - Understanding system components and patterns
Deployment Guide - Production deployment options