Configuration Management - Chris-Cullins/wiki_bot GitHub Wiki

Configuration Management

Overview

The Configuration Management area provides a centralized, environment-based configuration system for the wiki bot. It manages API credentials, repository settings, documentation generation options, and runtime behavior through environment variables. The system uses strongly-typed TypeScript interfaces to ensure type safety and provide clear documentation of all available configuration options.

Key Components

src/config.ts

Central configuration module that defines the configuration schema and provides environment variable loading. Exports the Config interface and loadConfig() function used throughout the application.

Type Definitions

  • Config: Main configuration interface defining all application settings
  • DocumentationDepth: Union type for documentation detail levels ('summary' | 'standard' | 'deep')
  • LlmProvider: Union type for LLM provider selection ('agent-sdk' | 'claude-cli' | 'codex-cli')
  • RepositoryMode: Imported from git repository manager, controls repository initialization behavior

How It Works

Configuration Loading Flow

  1. Environment Variable Parsing: loadConfig() reads from process.env and normalizes values
  2. Type Coercion: String environment variables are converted to appropriate types (booleans, enums)
  3. Fallback Logic: Provides sensible defaults when optional values are missing
  4. Validation: Throws errors for missing required values (e.g., API keys when not in test mode)
  5. Return: Produces a fully-typed Config object ready for application use

Provider Selection Logic

The LLM provider is selected based on LLM_PROVIDER environment variable with flexible matching:

// Accepts: 'claude-cli', 'claude' → 'claude-cli'
// Accepts: 'codex-cli', 'codex' → 'codex-cli'  
// Accepts: 'agent-sdk', 'anthropic' → 'agent-sdk'
// Default: 'agent-sdk'

Boolean Environment Variables

Multiple formats are supported for boolean flags:

  • Truthy: 'true', '1', 'yes'
  • Falsy: 'false', '0', 'no'
  • Undefined: Uses context-specific defaults

Important Configuration Options

API & Authentication

  • apiKey: Anthropic API key (from ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY). Required unless in test mode or using CLI providers.
  • baseURL: Optional custom Anthropic API endpoint
  • githubToken: Personal access token for GitHub wiki operations (from GITHUB_TOKEN or GH_TOKEN)

Repository Management

  • repoUrl: Target repository URL to document
  • repoPath: Local path to repository
  • wikiRepoUrl: Git URL for wiki repository (from GITHUB_WIKI_URL or WIKI_REPO_URL)
  • wikiRepoPath: Local checkout path for wiki (from GITHUB_WIKI_PATH or WIKI_REPO_PATH)
  • wikiRepoBranch: Branch for wiki commits
  • wikiRepoMode: Controls repository initialization ('fresh', 'incremental', 'reuse-or-clone')
  • wikiRepoShallow: Enable shallow cloning for performance
  • wikiFreshClean: Delete existing markdown files in fresh mode

Documentation Behavior

  • documentationDepth: Detail level - 'summary', 'standard', or 'deep' (from DOC_DEPTH)
  • incrementalDocs: Reuse existing wiki content for updates (auto-enabled for incremental/reuse-or-clone modes)
  • templateDir: Custom template directory path

Runtime & Debugging

  • testMode: Skip Agent SDK calls to save API costs (TEST_MODE=true)
  • debug: Enable verbose logging (DEBUG=true)
  • promptLoggingEnabled: Persist prompt/response transcripts (from PROMPT_LOG_ENABLED, defaults to debug value)
  • promptLogDir: Directory for prompt logs
  • llmProvider: Choose LLM backend ('agent-sdk', 'claude-cli', 'codex-cli')

Developer Notes

API Key Validation

The system only requires an Anthropic API key when using the agent-sdk provider. CLI providers (claude-cli, codex-cli) delegate authentication to their respective tools:

const requiresAnthropicKey = llmProvider === 'agent-sdk';
if (!apiKey && !testMode && requiresAnthropicKey) {
  throw new Error('ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY environment variable is required');
}

Incremental Documentation Logic

The incrementalDocs flag is automatically enabled when using incremental or reuse-or-clone repository modes, but can be explicitly overridden via INCREMENTAL_DOCS:

incrementalDocs = wikiRepoMode === 'incremental' || wikiRepoMode === 'reuse-or-clone';
// Unless explicitly set via INCREMENTAL_DOCS

Environment Variable Naming

Multiple aliases exist for backward compatibility:

  • Wiki URL: GITHUB_WIKI_URL or WIKI_REPO_URL
  • Wiki Path: GITHUB_WIKI_PATH or WIKI_REPO_PATH
  • GitHub Token: GITHUB_TOKEN or GH_TOKEN

Test Mode Behavior

When TEST_MODE=true, the API key defaults to 'test-mode-key' to allow development without valid credentials. This mode should be used for testing configuration loading and other non-LLM functionality.

Usage Examples

Loading Configuration

import { loadConfig } from './config.js';

const config = loadConfig();
console.log(`Using ${config.llmProvider} provider`);
console.log(`Documentation depth: ${config.documentationDepth}`);

Environment Setup for Production

export ANTHROPIC_API_KEY="sk-ant-..."
export GITHUB_TOKEN="ghp_..."
export REPO_URL="https://github.com/user/repo"
export GITHUB_WIKI_URL="https://github.com/user/repo.wiki.git"
export WIKI_REPO_MODE="incremental"
export DOC_DEPTH="standard"
npm start

Development with Test Mode

export TEST_MODE=true
export DEBUG=true
export PROMPT_LOG_ENABLED=true
export PROMPT_LOG_DIR="./logs"
export REPO_PATH="./local-repo"
npm run dev

Using Alternative LLM Providers

# Use Claude CLI instead of Agent SDK
export LLM_PROVIDER="claude-cli"
export REPO_URL="https://github.com/user/repo"
npm start

Related Configuration Files

  • package.json: Defines build scripts that copy prompts and templates to dist directory
  • tsconfig.json: TypeScript strict mode ensures type safety for configuration values
  • .gitignore: Excludes .env* files to prevent credential leakage
  • .claude/settings.local.json: Configures permissions for GitHub CLI operations