CTX: Context as Code (CaC) tool

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is **CTX** (Context Generator), a PHP 8.3+ tool for generating contextual documentation from codebases for use with LLMs. It allows developers to create structured context files from various sources including local files, Git repositories, GitHub/GitLab repos, web pages, and MCP servers. ## Development Commands ### Primary Commands - `composer install` - Install dependencies - `php ctx` or `./ctx` - Run the context generator (main entry point) - `php ctx init` - Initialize a new context.yaml configuration file - `php ctx generate` - Generate context files from configuration (alias: `build`, `compile`) - `php ctx server` - Start the MCP server for Claude AI integration - `php ctx schema` - Generate JSON schema for configuration validation ### Development & Testing - `composer test` - Run PHPUnit tests - `composer test:cc` - Run tests with coverage report - `composer cs-check` - Check code style with PHP-CS-Fixer (dry run) - `composer cs-fix` - Fix code style issues - `composer psalm` - Run Psalm static analysis - `composer psalm:ci` - Run Psalm with CI formatting - `composer refactor` - Run Rector for automated refactoring - `composer refactor:ci` - Run Rector in dry-run mode ### Build Commands The project uses Box to create PHAR executables: - Build output goes to `.build/phar/ctx.phar` - Configuration in `box.json` ## Architecture Overview ### Core Application Structure - **Spiral Framework**: Built on Spiral PHP framework using dependency injection - **Console Commands**: Located in `src/Console/` extending `BaseCommand` - **Bootloaders**: Application services bootstrapped via bootloaders in `src/Application/Bootloader/` - **Entry Point**: `ctx` script → `app.php` → Spiral application kernel ### Key Components #### Configuration System (`src/Config/`) - **YAML-based configuration** with JSON schema validation - **Import system** supports importing from URLs and local paths - **Environment variables** supported throughout configuration - **Modular parsing** with plugin system for extensibility #### Source System (`src/Source/`) Multiple source types for gathering content: - **File sources** - Local files with pattern matching and filtering - **Git sources** - Git diffs, commits, and repository content - **GitHub/GitLab sources** - Remote repository integration - **URL sources** - Web page content with CSS selectors - **Text sources** - Plain text content - **Composer sources** - Package information and dependencies - **Tree sources** - Directory structure visualization #### Content Processing (`src/Lib/`) - **Content blocks** - Modular content representation (code, text, comments, etc.) - **Renderers** - Convert content blocks to markdown output - **Modifiers** - Transform content (PHP signatures, sanitization, filtering) - **Token counting** - Track content size for LLM context limits #### Document Compilation (`src/Document/`) - **Document compiler** processes configuration and generates output files - **Error handling** with detailed source-level error reporting - **Multi-document support** with different output paths #### MCP Server Integration (`src/McpServer/`) - **Model Context Protocol server** for direct Claude AI integration - **Resource and prompt management** - **Project-based organization** for multi-project support ### Key Patterns - **Immutable DTOs**: Heavy use of readonly classes and value objects - **Interface segregation**: Clear interfaces for all major components - **Factory pattern**: Factories for creating configured instances - **Registry pattern**: Centralized registration of sources, modifiers, etc. - **Bootloader pattern**: Spiral-style service registration and configuration ## Configuration Structure The main configuration file is `context.yaml` with JSON schema at `json-schema.json`. Key sections: - **documents**: Array of document configurations with sources and output paths - **sources**: Various content sources (file, git, github, url, text, etc.) - **modifiers**: Content transformations (php-signature, sanitizer, etc.) - **import**: Include other configuration files or URLs - **exclude**: Global exclusion patterns and paths ## Using Context Configuration The project includes a `context.yaml` file that defines how to generate contextual documentation: ### Generating Context Files - `ctx` - Generate all context files defined in context.yaml - `ctx generate` - Same as above (explicit command) ### Current Context Documents Look at generated context files in `.context/` to see what context files are generated. The configuration generates these context files: - `project-structure.md` - Tree view of src/ directory with file sizes - `core/interfaces.md` - All PHP interface files - `console/commands.md` - Console commands extending BaseCommand - `changes.md` - Git diff of unstaged changes ### Context Configuration Features - **Import system**: Automatically imports `src/**/context.yaml` files and external URL configurations - **Global exclusions**: Excludes tests, vendor, config files, and development artifacts - **Modular documents**: Each document targets specific code patterns (interfaces, commands, etc.) - **Change tracking**: Automatically includes current development changes via git diff Use `ctx` to generate up-to-date context files before sharing code with LLMs. ## Testing - Tests located in `tests/src/` - PHPUnit configuration in `phpunit.xml` - Coverage reports generated to `.build/phpunit/logs/` ## Code Quality - **PHP-CS-Fixer** for code style enforcement - **Psalm** for static analysis with strict type checking - **Rector** for automated refactoring to modern PHP standards - **Strict typing**: All files use `declare(strict_types=1)` ## Development Lessons Learned ### Key Observations from Spec-Flow Implementation #### 1. **PHP Enum Naming Conventions** - **Mistake**: Initially used `SCREAMING_SNAKE_CASE` for PHP enum cases - **Correction**: PHP enums should use `camelCase` format (e.g., `FlowStatus::InProgress`) - **Rule**: Follow modern PHP 8.1+ enum conventions, not legacy constant patterns #### 2. **Namespace Consistency** - **Mistake**: Started with `CTX\SpecFlow\*` namespace - **Correction**: Must follow existing codebase pattern: `Butschster\ContextGenerator\SpecFlow\*` - **Rule**: Always check existing namespace patterns before creating new modules #### 3. **MCP Integration Patterns** - **Mistake**: Created console commands + shell execution approach - **Correction**: Use direct PHP action classes with MCP attributes - **Rule**: CTX uses attribute-based MCP actions, not shell command wrappers - **Pattern**: `#[Tool(name: 'tool_name')] + #[Post(path: '/tools/tool_name')]` #### 4. **Tool Provider Anti-Pattern** - **Mistake**: Created `SpecFlowToolProvider` implementing `ToolProviderInterface` - **Correction**: CTX auto-discovers tools via attributes, no manual registration needed - **Rule**: Let CTX's attribute scanning handle tool discovery automatically