fix: Add external repository support for repro command (v0.20.1) (#52)

* fix: add external repository support for repro command (0.20.1)

- Add environment manager detection (hatch, poetry, uv, pip)
- Make all validation tools optional with clear messaging
- Add dynamic source directory detection
- Update documentation for external repo support
- Add comprehensive test coverage (25 new tests)

Fixes critical design issue where repro command only worked on
SpecFact CLI's own codebase. Now works on external repositories
without requiring SpecFact CLI adoption.

Closes: External repository support issue
Reference: CRITICAL_DESIGN_ISSUE_EXTERNAL_REPO_SUPPORT.md

* fix: add external repository support for generate commands (0.20.1)

- Fix generate contracts-apply: use dynamic source/test detection
- Fix generate test-prompt: use dynamic source directory detection
- Add test directory detection utilities (detect_test_directories, find_test_files_for_source)
- Use environment detection for Python/pytest invocations
- Add comprehensive tests (6 new tests for test detection utilities)

Completes external repository support fixes identified in analysis.
All generate commands now work on external repositories.

* test: add comprehensive tests for repro setup and init environment warning

- Add 15 integration tests for repro setup command covering:
  - pyproject.toml creation and updates with CrossHair config
  - Environment manager detection (hatch, poetry, uv, pip)
  - Source directory detection (src/, lib/, package name)
  - CrossHair tool availability checking and installation
  - Error handling and user guidance
- Add 5 e2e tests for init command environment manager warning:
  - Warning display when no environment manager detected
  - No warning when hatch/poetry/pip/uv detected
- Update CHANGELOG.md with new features and test coverage improvements

All tests passing (20/20)

* feat: align init --install-deps with environment manager detection

- Update init --install-deps to use build_tool_command for environment-aware installation
- Automatically detect and use hatch, poetry, uv, or pip based on project configuration
- Show detected environment manager message and command being used
- Provide environment-specific installation guidance on errors
- Add 5-minute timeout for package installation
- Track environment manager in telemetry
- Update help text to reflect environment manager awareness
- Update CHANGELOG.md with improvements

This ensures consistent behavior with repro setup command and proper
integration with different Python project management tools.

---------

Co-authored-by: Dominikus Nold <[email protected]>

Author: djm81

CHANGELOG.md

@@ -9,6 +9,64 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.20.1] - 2025-12-20
+
+### Fixed (0.20.1)
+
+- **External Repository Support**: Fixed critical issue where `repro` command only worked on SpecFact CLI's own codebase
+  - Added automatic environment manager detection (hatch, poetry, uv, pip)
+  - Made all validation tools optional with clear messaging when unavailable
+  - Added dynamic source directory detection (src/, lib/, or package name from pyproject.toml)
+  - Commands now work on external repositories without requiring SpecFact CLI adoption
+  - Enables OSS validation plan execution as designed
+- **`generate contracts-apply` Command**: Fixed hardcoded paths and environment assumptions
+  - Uses dynamic source directory detection instead of hardcoded `src/` paths
+  - Uses environment detection for Python/pytest invocations
+  - Dynamic test file detection (supports multiple test directory structures)
+  - Works on external repositories with different project structures
+- **`generate test-prompt` Command**: Fixed hardcoded source directory detection
+  - Uses dynamic source directory detection instead of hardcoded `src/`
+  - Dynamic test file detection for better external repository support
+
+### Added (0.20.1)
+
+- **Environment Manager Detection**: New `env_manager` utility module for detecting and working with different Python environment managers
+- **Test Directory Detection**: New utilities for detecting test directories and finding test files dynamically
+- **Comprehensive Tests**: Added 31 new tests for environment detection, test directory detection, and external repository support
+- **`repro setup` Command**: New subcommand to automatically configure CrossHair for contract exploration
+  - Automatically generates `[tool.crosshair]` configuration in `pyproject.toml`
+  - Detects source directories and environment managers
+  - Provides installation guidance for crosshair-tool
+  - Optional `--install-crosshair` flag to attempt automatic installation
+- **`init` Command Environment Warning**: Added warning when no compatible environment manager is detected
+  - Non-blocking warning that provides guidance on supported tools
+  - Helps users understand best practices for SpecFact CLI integration
+  - Lists supported environment managers (hatch, poetry, uv, pip) with detection criteria
+
+### Improved (0.20.1)
+
+- **Documentation**: Updated `repro` command documentation to clarify external repository support and environment requirements
+  - Added `repro setup` command documentation
+  - Updated all example flows to include CrossHair setup step
+  - Added "Supported Project Management Tools" section to installation guide
+- **Error Messages**: Improved messaging when tools are unavailable, providing clear guidance on installation
+- **Code Quality**: All linting/formatting tools in `generate contracts-apply` now use environment detection
+- **Test Coverage**: Added comprehensive test suite for `repro setup` command (15 tests) and `init` command environment warning (5 tests)
+- **`init --install-deps` Command**: Now uses environment manager detection for package installation
+  - Automatically detects and uses hatch, poetry, uv, or pip based on project configuration
+  - Provides environment-specific installation commands and error guidance
+  - Shows detected environment manager and command being used
+  - Adds timeout handling and improved error messages
+  - Tracks environment manager in telemetry
+
+### Notes (0.20.1)
+
+This patch release fixes the critical design issue identified during OSS validation planning. The `repro` command can now be used to validate external repositories (Requests, Flask, FastAPI, etc.) without requiring those projects to adopt SpecFact CLI.
+
+**Reference**: [CRITICAL_DESIGN_ISSUE_EXTERNAL_REPO_SUPPORT.md](docs/internal/analysis/CRITICAL_DESIGN_ISSUE_EXTERNAL_REPO_SUPPORT.md)
+
+---
+
 ## [0.20.0] - 2025-12-17
 
 ### 🎉 Long-Term Stable (LTS) Release

docs/examples/integration-showcases/integration-showcases-testing-guide.md

@@ -1035,11 +1035,17 @@ Report written to: .specfact/projects/<bundle-name>/reports/enforcement/report-<
   - Type checking (basedpyright) - type annotations and type safety
 
 - **Conditionally runs** (only if present):
-  - Contract exploration (CrossHair) - only if `src/` directory exists (symbolic execution to find counterexamples, not runtime contract validation)
+  - Contract exploration (CrossHair) - only if `[tool.crosshair]` config exists in `pyproject.toml` (use `specfact repro setup` to generate) and `src/` directory exists (symbolic execution to find counterexamples, not runtime contract validation)
   - Semgrep async patterns - only if `tools/semgrep/async.yml` exists (requires semgrep installed)
   - Property tests (pytest) - only if `tests/contracts/` directory exists
   - Smoke tests (pytest) - only if `tests/smoke/` directory exists
 
+**CrossHair Setup**: Before running `repro` for the first time, set up CrossHair configuration:
+```bash
+specfact repro setup
+```
+This automatically generates `[tool.crosshair]` configuration in `pyproject.toml` to enable contract exploration.
+
 **Important**: `repro` does **not** perform runtime contract validation (checking `@icontract` decorators at runtime). It runs static analysis (linting, type checking) and symbolic execution (CrossHair) for contract exploration. Type mismatches will be detected by the type checking tool (basedpyright) if available. The enforcement configuration determines whether failures block the workflow.
 
 ### Example 3 - Step 6: Verify Results

docs/examples/quick-examples.md

@@ -174,6 +174,9 @@ specfact enforce sdd
 ## Validation
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
 # Quick validation
 specfact repro
 

docs/getting-started/first-steps.md

@@ -106,13 +106,17 @@ specfact bridge constitution bootstrap --repo .
 ### Step 3: Find and Fix Gaps
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
 # Analyze and validate your codebase
 specfact repro --verbose
 ```
 
 **What happens**:
 
-- Runs the full validation suite (linting, type checking, contracts, tests)
+- `repro setup` configures CrossHair for contract exploration (one-time setup)
+- `repro` runs the full validation suite (linting, type checking, contracts, tests)
 - Identifies gaps and issues in your codebase
 - Generates enforcement reports that downstream tools (like `generate fix-prompt`) can use
 

docs/getting-started/installation.md

@@ -125,6 +125,9 @@ jobs:
       - name: Install SpecFact CLI
         run: pip install specfact-cli
 
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
       - name: Run Contract Validation
         run: specfact repro --verbose --budget 90
 
@@ -322,6 +325,104 @@ specfact sync repository --repo . --watch
 - **Bidirectional sync**: Use `sync bridge --adapter <adapter>` or `sync repository` for ongoing change management
 - **Semgrep (optional)**: Install `pip install semgrep` for async pattern detection in `specfact repro`
 
+---
+
+## Supported Project Management Tools
+
+SpecFact CLI automatically detects and works with the following Python project management tools. **No configuration needed** - it detects your project's environment manager automatically!
+
+### Automatic Detection
+
+When you run SpecFact CLI commands on a repository, it automatically:
+
+1. **Detects the environment manager** by checking for configuration files
+2. **Detects source directories** (`src/`, `lib/`, or package name from `pyproject.toml`)
+3. **Builds appropriate commands** using the detected environment manager
+4. **Checks tool availability** and skips with clear messages if tools are missing
+
+### Supported Tools
+
+#### 1. **hatch** - Modern Python project manager
+
+- **Detection**: `[tool.hatch]` section in `pyproject.toml`
+- **Command prefix**: `hatch run`
+- **Example**: `hatch run pytest tests/`
+- **Use case**: Modern Python projects using hatch for build and dependency management
+
+#### 2. **poetry** - Dependency management and packaging
+
+- **Detection**: `[tool.poetry]` section in `pyproject.toml` or `poetry.lock` file
+- **Command prefix**: `poetry run`
+- **Example**: `poetry run pytest tests/`
+- **Use case**: Projects using Poetry for dependency management
+
+#### 3. **uv** - Fast Python package installer and resolver
+
+- **Detection**: `[tool.uv]` section in `pyproject.toml`, `uv.lock`, or `uv.toml` file
+- **Command prefix**: `uv run`
+- **Example**: `uv run pytest tests/`
+- **Use case**: Projects using uv for fast package management
+
+#### 4. **pip** - Standard Python package installer
+
+- **Detection**: `requirements.txt` or `setup.py` file
+- **Command prefix**: Direct tool invocation (no prefix)
+- **Example**: `pytest tests/`
+- **Use case**: Traditional Python projects using pip and virtual environments
+
+### Detection Priority
+
+SpecFact CLI checks in this order:
+
+1. `pyproject.toml` for tool sections (`[tool.hatch]`, `[tool.poetry]`, `[tool.uv]`)
+2. Lock files (`poetry.lock`, `uv.lock`, `uv.toml`)
+3. Fallback to `requirements.txt` or `setup.py` for pip-based projects
+
+### Source Directory Detection
+
+SpecFact CLI automatically detects source directories:
+
+- **Standard layouts**: `src/`, `lib/`
+- **Package name**: Extracted from `pyproject.toml` (e.g., `my-package` → `my_package/`)
+- **Root-level**: Falls back to root directory if no standard layout found
+
+### Example: Working with Different Projects
+
+```bash
+# Hatch project
+cd /path/to/hatch-project
+specfact repro --repo .  # Automatically uses "hatch run" for tools
+
+# Poetry project
+cd /path/to/poetry-project
+specfact repro --repo .  # Automatically uses "poetry run" for tools
+
+# UV project
+cd /path/to/uv-project
+specfact repro --repo .  # Automatically uses "uv run" for tools
+
+# Pip project
+cd /path/to/pip-project
+specfact repro --repo .  # Uses direct tool invocation
+```
+
+### External Repository Support
+
+SpecFact CLI works seamlessly on **external repositories** without requiring:
+
+- ❌ SpecFact CLI adoption
+- ❌ Specific project structures
+- ❌ Manual configuration
+- ❌ Tool installation in global environment
+
+**All commands automatically adapt to the target repository's environment and structure.**
+
+This makes SpecFact CLI ideal for:
+
+- **OSS validation workflows** - Validate external open-source projects
+- **Multi-project environments** - Work with different project structures
+- **CI/CD pipelines** - Validate any Python project without setup
+
 ## Common Commands
 
 ```bash

docs/guides/migration-0.16-to-0.19.md

@@ -34,6 +34,9 @@ specfact implement tasks .specfact/projects/my-bundle/tasks.yaml
 Use the new bridge commands instead:
 
 ```bash
+# Set up CrossHair for contract exploration (one-time setup, only available since v0.20.1)
+specfact repro setup
+
 # Analyze and validate your codebase
 specfact repro --verbose
 

docs/guides/speckit-journey.md

@@ -252,6 +252,9 @@ specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirec
 # Start in shadow mode (observe only)
 specfact enforce stage --preset minimal
 
+# Set up CrossHair for contract exploration
+specfact repro setup
+
 # Review what would be blocked
 specfact repro --verbose
 
@@ -285,6 +288,7 @@ specfact repro --fix  # Apply Semgrep auto-fixes, then validate
 specfact enforce stage --preset strict
 
 # Full automation (CI/CD, brownfield analysis, etc.)
+# (CrossHair setup already done in Week 3)
 specfact repro --budget 120 --verbose
 ```
 
@@ -411,6 +415,9 @@ specfact enforce stage --preset strict
 ### **Step 6: Validate**
 
 ```bash
+# Set up CrossHair for contract exploration (one-time setup)
+specfact repro setup
+
 # Run all checks
 specfact repro --verbose
 

docs/guides/use-cases.md

@@ -310,6 +310,10 @@ specfact enforce stage --preset strict
 #### 7. Validate
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Run validation
 specfact repro --verbose
 ```
 
@@ -440,6 +444,9 @@ specfact enforce stage --preset strict
 #### 5. Validate Continuously
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
 # During development
 specfact repro
 
@@ -505,6 +512,9 @@ jobs:
       - name: Install SpecFact CLI
         run: pip install specfact-cli
 
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
       - name: Run Contract Validation
         run: specfact repro --verbose --budget 90
 
@@ -625,6 +635,9 @@ specfact plan compare \
 #### 4. Enforce Consistency
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
 # Add to CI
 specfact repro
 specfact plan compare --manual contracts/shared/plan.bundle.yaml --auto .

docs/guides/workflows.md

@@ -254,6 +254,9 @@ specfact enforce stage --preset strict
 ### Running Validation
 
 ```bash
+# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
 # Quick validation
 specfact repro
 
@@ -266,7 +269,8 @@ specfact repro --fix --budget 120
 
 **What it does**:
 
-- Validates contracts
+- `repro setup` configures CrossHair for contract exploration (one-time setup)
+- `repro` validates contracts
 - Checks types
 - Detects async anti-patterns
 - Validates state machines