specfact-cli 0.6.4__tar.gz → 0.6.6__tar.gz

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.6.4
+Version: 0.6.6
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.6.4"
+version = "0.6.6"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -106,6 +106,7 @@ Trademarks = "https://github.com/nold-ai/specfact-cli/blob/main/TRADEMARKS.md"
 
 [project.scripts]
 specfact = "specfact_cli.cli:cli_main"
+specfact-cli = "specfact_cli.cli:cli_main"  # Alias for uvx compatibility
 
 # [project.entry-points."pytest11"] # Add if you have pytest plugins
 # specfact_test_plugin = "specfact_cli.pytest_plugin"

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/resources/prompts/specfact-import-from-code.md

@@ -134,7 +134,11 @@ When in copilot mode, follow this three-phase workflow:
 **ALWAYS execute CLI first** to get structured, validated output:
 
 ```bash
+# Full repository analysis
 specfact import from-code --repo <path> --name <name> --confidence <score>
+
+# Partial repository analysis (analyze only specific subdirectory)
+specfact import from-code --repo <path> --name <name> --entry-point <subdirectory> --confidence <score>
 ```
 
 **Note**: Mode is auto-detected by the CLI (CI/CD in non-interactive environments, CoPilot when in IDE/Copilot session). No need to specify `--mode` flag.
@@ -245,6 +249,11 @@ Extract arguments from user input:
 - `--report PATH` - Analysis report path (optional, default: `.specfact/reports/brownfield/analysis-<timestamp>.md`)
 - `--shadow-only` - Observe mode without enforcing (optional)
 - `--key-format {classname|sequential}` - Feature key format (default: `classname`)
+- `--entry-point PATH` - Subdirectory path for partial analysis (relative to repo root). Analyzes only files within this directory and subdirectories. Useful for:
+  - Multi-project repositories (monorepos): Analyze one project at a time
+  - Large codebases: Focus on specific modules or subsystems
+  - Incremental modernization: Modernize one part of the codebase at a time
+  - Example: `--entry-point projects/api-service` analyzes only `projects/api-service/` and its subdirectories
 
 **Important**: If `--name` is not provided, **ask the user interactively** for a meaningful plan name and **WAIT for their response**. The name will be automatically sanitized (lowercased, spaces/special chars removed) for filesystem persistence.
 
@@ -261,7 +270,11 @@ For single quotes in args like "I'm Groot", use escape syntax: e.g `'I'\''m Groo
 **ALWAYS execute the specfact CLI first** to get structured, validated output:
 
 ```bash
+# Full repository analysis
 specfact import from-code --repo <repo_path> --name <plan_name> --confidence <confidence>
+
+# Partial repository analysis (analyze only specific subdirectory)
+specfact import from-code --repo <repo_path> --name <plan_name> --entry-point <subdirectory> --confidence <confidence>
 ```
 
 **Note**: Mode is auto-detected by the CLI. No need to specify `--mode` flag.

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/resources/prompts/specfact-plan-review.md

@@ -50,7 +50,10 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **For updating features**:
 
-- `specfact plan update-feature --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance> --constraints <constraints> --confidence <confidence> --draft <true/false> --plan <path>`
+- `specfact plan update-feature --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance> --constraints <constraints> --confidence <confidence> --draft/--no-draft --plan <path>`
+  - **Boolean flags**: `--draft` sets True, `--no-draft` sets False, omit to leave unchanged
+  - ❌ **WRONG**: `--draft true` or `--draft false` (Typer boolean flags don't accept values)
+  - ✅ **CORRECT**: `--draft` (sets True) or `--no-draft` (sets False)
   - Updates existing feature metadata (title, outcomes, acceptance criteria, constraints, confidence, draft status)
   - Works in CI/CD, Copilot, and interactive modes
   - Example: `specfact plan update-feature --key FEATURE-001 --title "New Title" --outcomes "Outcome 1, Outcome 2"`

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/resources/prompts/specfact-plan-update-feature.md

@@ -85,7 +85,7 @@ The `specfact plan update-feature` command:
 - Acceptance criteria (optional, comma-separated)
 - Constraints (optional, comma-separated)
 - Confidence (optional, 0.0-1.0)
-- Draft status (optional, true/false)
+- Draft status (optional, boolean flag: `--draft` sets True, `--no-draft` sets False, omit to leave unchanged)
 - Plan bundle path (optional, defaults to active plan or `.specfact/plans/main.bundle.yaml`)
 
 **WAIT STATE**: If feature key is missing, ask the user:
@@ -155,10 +155,16 @@ specfact plan update-feature \
   --constraints "Python 3.11+, Test coverage >= 80%" \
   --plan <plan_path>
 
-# Mark as draft
+# Mark as draft (boolean flag: --draft sets True, --no-draft sets False)
 specfact plan update-feature \
   --key FEATURE-001 \
-  --draft true \
+  --draft \
+  --plan <plan_path>
+
+# Unmark draft (set to False)
+specfact plan update-feature \
+  --key FEATURE-001 \
+  --no-draft \
   --plan <plan_path>
 ```
 
@@ -209,7 +215,9 @@ specfact plan update-feature \
 - **Partial updates**: Only specified fields are updated, others remain unchanged
 - **Comma-separated lists**: Outcomes, acceptance, and constraints use comma-separated strings
 - **Confidence range**: Must be between 0.0 and 1.0
-- **Draft status**: Use `true` or `false` (boolean)
+- **Draft status**: Boolean flag - use `--draft` to set True, `--no-draft` to set False, omit to leave unchanged
+  - ❌ **WRONG**: `--draft true` or `--draft false` (Typer boolean flags don't accept values)
+  - ✅ **CORRECT**: `--draft` (sets True) or `--no-draft` (sets False) or omit (leaves unchanged)
 
 ### Field Guidelines
 

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.6.4"
+__version__ = "0.6.6"

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/specfact_cli/__init__.py

@@ -9,6 +9,6 @@ This package provides command-line tools for:
 - Validating reproducibility
 """
 
-__version__ = "0.6.4"
+__version__ = "0.6.6"
 
 __all__ = ["__version__"]

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/specfact_cli/cli.py

@@ -101,6 +101,7 @@ app = typer.Typer(
     help="SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development",
     add_completion=True,  # Enable Typer's built-in completion (works natively for bash/zsh/fish without extensions)
     rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},  # Add -h as alias for --help
 )
 
 console = Console()
@@ -173,6 +174,12 @@ def main(
     - Auto-detect from environment (CoPilot API, IDE integration)
     - Default to CI/CD mode
     """
+    # Show help if no command provided (avoids user confusion)
+    if ctx.invoked_subcommand is None:
+        # Show help by calling Typer's help callback
+        ctx.get_help()
+        raise typer.Exit()
+
     # Store mode in context for commands to access
     if ctx.obj is None:
         ctx.obj = {}

specfact_cli-0.6.6/src/specfact_cli/commands/init.py

@@ -0,0 +1,294 @@
+"""
+Init command - Initialize SpecFact for IDE integration.
+
+This module provides the `specfact init` command to copy prompt templates
+to IDE-specific locations for slash command integration.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from beartype import beartype
+from icontract import ensure, require
+from rich.console import Console
+from rich.panel import Panel
+
+from specfact_cli.telemetry import telemetry
+from specfact_cli.utils.ide_setup import (
+    IDE_CONFIG,
+    copy_templates_to_ide,
+    detect_ide,
+    find_package_resources_path,
+    get_package_installation_locations,
+)
+
+
+app = typer.Typer(help="Initialize SpecFact for IDE integration")
+console = Console()
+
+
+def _is_valid_repo_path(path: Path) -> bool:
+    """Check if path exists and is a directory."""
+    return path.exists() and path.is_dir()
+
+
+@app.callback(invoke_without_command=True)
+@require(lambda ide: ide in IDE_CONFIG or ide == "auto", "IDE must be valid or 'auto'")
+@require(lambda repo: _is_valid_repo_path(repo), "Repo path must exist and be directory")
+@ensure(lambda result: result is None, "Command should return None")
+@beartype
+def init(
+    ide: str = typer.Option(
+        "auto",
+        "--ide",
+        help="IDE type (auto, cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q)",
+    ),
+    repo: Path = typer.Option(
+        Path("."),
+        "--repo",
+        help="Repository path (default: current directory)",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite existing files",
+    ),
+) -> None:
+    """
+    Initialize SpecFact for IDE integration.
+
+    Copies prompt templates to IDE-specific locations so slash commands work.
+    This command detects the IDE type (or uses --ide flag) and copies
+    SpecFact prompt templates to the appropriate directory.
+
+    Examples:
+        specfact init                    # Auto-detect IDE
+        specfact init --ide cursor       # Initialize for Cursor
+        specfact init --ide vscode --force  # Overwrite existing files
+        specfact init --repo /path/to/repo --ide copilot
+    """
+    telemetry_metadata = {
+        "ide": ide,
+        "force": force,
+    }
+
+    with telemetry.track_command("init", telemetry_metadata) as record:
+        # Resolve repo path
+        repo_path = repo.resolve()
+
+        # Detect IDE
+        detected_ide = detect_ide(ide)
+        ide_config = IDE_CONFIG[detected_ide]
+        ide_name = ide_config["name"]
+
+        console.print()
+        console.print(Panel("[bold cyan]SpecFact IDE Setup[/bold cyan]", border_style="cyan"))
+        console.print(f"[cyan]Repository:[/cyan] {repo_path}")
+        console.print(f"[cyan]IDE:[/cyan] {ide_name} ({detected_ide})")
+        console.print()
+
+        # Find templates directory
+        # Priority order:
+        # 1. Development: relative to project root (resources/prompts)
+        # 2. Installed package: use importlib.resources to find package location
+        # 3. Fallback: try relative to this file (for edge cases)
+        templates_dir: Path | None = None
+        package_templates_dir: Path | None = None
+        tried_locations: list[Path] = []
+
+        # Try 1: Development mode - relative to repo root
+        dev_templates_dir = (repo_path / "resources" / "prompts").resolve()
+        tried_locations.append(dev_templates_dir)
+        console.print(f"[dim]Debug:[/dim] Trying development path: {dev_templates_dir}")
+        if dev_templates_dir.exists():
+            templates_dir = dev_templates_dir
+            console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+        else:
+            console.print("[dim]Debug:[/dim] Development path not found, trying installed package...")
+            # Try 2: Installed package - use importlib.resources
+            # Note: importlib is part of Python's standard library (since Python 3.1)
+            # importlib.resources.files() is available since Python 3.9
+            # Since we require Python >=3.11, this should always be available
+            # However, we catch exceptions for robustness (minimal installations, edge cases)
+            package_templates_dir = None
+            try:
+                import importlib.resources
+
+                console.print("[dim]Debug:[/dim] Using importlib.resources.files() API...")
+                # Use files() API (Python 3.9+) - recommended approach
+                resources_ref = importlib.resources.files("specfact_cli")
+                templates_ref = resources_ref / "resources" / "prompts"
+                # Convert Traversable to Path
+                # Traversable objects can be converted to Path via str()
+                # Use resolve() to handle Windows/Linux/macOS path differences
+                package_templates_dir = Path(str(templates_ref)).resolve()
+                tried_locations.append(package_templates_dir)
+                console.print(f"[dim]Debug:[/dim] Package templates path: {package_templates_dir}")
+                if package_templates_dir.exists():
+                    templates_dir = package_templates_dir
+                    console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+                else:
+                    console.print("[yellow]⚠[/yellow] Package templates path exists but directory not found")
+            except (ImportError, ModuleNotFoundError) as e:
+                console.print(
+                    f"[yellow]⚠[/yellow] importlib.resources not available or module not found: {type(e).__name__}: {e}"
+                )
+                console.print("[dim]Debug:[/dim] Falling back to importlib.util.find_spec()...")
+            except (TypeError, AttributeError, ValueError) as e:
+                console.print(f"[yellow]⚠[/yellow] Error converting Traversable to Path: {e}")
+                console.print("[dim]Debug:[/dim] Falling back to importlib.util.find_spec()...")
+            except Exception as e:
+                console.print(f"[yellow]⚠[/yellow] Unexpected error with importlib.resources: {type(e).__name__}: {e}")
+                console.print("[dim]Debug:[/dim] Falling back to importlib.util.find_spec()...")
+
+            # Fallback: importlib.util.find_spec() + comprehensive package location search
+            if not templates_dir or not templates_dir.exists():
+                try:
+                    import importlib.util
+
+                    console.print("[dim]Debug:[/dim] Using importlib.util.find_spec() fallback...")
+                    spec = importlib.util.find_spec("specfact_cli")
+                    if spec and spec.origin:
+                        # spec.origin points to __init__.py
+                        # Go up to package root, then to resources/prompts
+                        # Use resolve() for cross-platform compatibility
+                        package_root = Path(spec.origin).parent.resolve()
+                        package_templates_dir = (package_root / "resources" / "prompts").resolve()
+                        tried_locations.append(package_templates_dir)
+                        console.print(f"[dim]Debug:[/dim] Package root from spec.origin: {package_root}")
+                        console.print(f"[dim]Debug:[/dim] Templates path from spec: {package_templates_dir}")
+                        if package_templates_dir.exists():
+                            templates_dir = package_templates_dir
+                            console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+                        else:
+                            console.print("[yellow]⚠[/yellow] Templates path from spec not found")
+                    else:
+                        console.print("[yellow]⚠[/yellow] Could not find specfact_cli module spec")
+                        if spec is None:
+                            console.print("[dim]Debug:[/dim] spec is None")
+                        elif not spec.origin:
+                            console.print("[dim]Debug:[/dim] spec.origin is None or empty")
+                except Exception as e:
+                    console.print(f"[yellow]⚠[/yellow] Error with importlib.util.find_spec(): {type(e).__name__}: {e}")
+
+            # Fallback: Comprehensive package location search (cross-platform)
+            if not templates_dir or not templates_dir.exists():
+                try:
+                    console.print("[dim]Debug:[/dim] Searching all package installation locations...")
+                    package_locations = get_package_installation_locations("specfact_cli")
+                    console.print(f"[dim]Debug:[/dim] Found {len(package_locations)} possible package location(s)")
+                    for i, loc in enumerate(package_locations, 1):
+                        console.print(f"[dim]Debug:[/dim]   {i}. {loc}")
+                        # Check for resources/prompts in this package location
+                        resource_path = (loc / "resources" / "prompts").resolve()
+                        tried_locations.append(resource_path)
+                        if resource_path.exists():
+                            templates_dir = resource_path
+                            console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+                            break
+                    if not templates_dir or not templates_dir.exists():
+                        # Try using the helper function as a final attempt
+                        console.print("[dim]Debug:[/dim] Trying find_package_resources_path() helper...")
+                        resource_path = find_package_resources_path("specfact_cli", "resources/prompts")
+                        if resource_path and resource_path.exists():
+                            tried_locations.append(resource_path)
+                            templates_dir = resource_path
+                            console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+                        else:
+                            console.print("[yellow]⚠[/yellow] Resources not found in any package location")
+                except Exception as e:
+                    console.print(f"[yellow]⚠[/yellow] Error searching package locations: {type(e).__name__}: {e}")
+
+            # Try 3: Fallback - relative to this file (for edge cases)
+            if not templates_dir or not templates_dir.exists():
+                try:
+                    console.print("[dim]Debug:[/dim] Trying fallback: relative to __file__...")
+                    # Get the directory containing this file (init.py)
+                    # init.py is in: src/specfact_cli/commands/init.py
+                    # Go up: commands -> specfact_cli -> src -> project root
+                    current_file = Path(__file__).resolve()
+                    fallback_dir = (current_file.parent.parent.parent.parent / "resources" / "prompts").resolve()
+                    tried_locations.append(fallback_dir)
+                    console.print(f"[dim]Debug:[/dim] Current file: {current_file}")
+                    console.print(f"[dim]Debug:[/dim] Fallback templates path: {fallback_dir}")
+                    if fallback_dir.exists():
+                        templates_dir = fallback_dir
+                        console.print(f"[green]✓[/green] Found templates at: {templates_dir}")
+                    else:
+                        console.print("[yellow]⚠[/yellow] Fallback path not found")
+                except Exception as e:
+                    console.print(f"[yellow]⚠[/yellow] Error with __file__ fallback: {type(e).__name__}: {e}")
+
+        if not templates_dir or not templates_dir.exists():
+            console.print()
+            console.print("[red]Error:[/red] Templates directory not found after all attempts")
+            console.print()
+            console.print("[yellow]Tried locations:[/yellow]")
+            for i, location in enumerate(tried_locations, 1):
+                exists = "✓" if location.exists() else "✗"
+                console.print(f"  {i}. {exists} {location}")
+            console.print()
+            console.print("[yellow]Debug information:[/yellow]")
+            console.print(f"  - Python version: {sys.version}")
+            console.print(f"  - Platform: {sys.platform}")
+            console.print(f"  - Current working directory: {Path.cwd()}")
+            console.print(f"  - Repository path: {repo_path}")
+            console.print(f"  - __file__ location: {Path(__file__).resolve()}")
+            try:
+                import importlib.util
+
+                spec = importlib.util.find_spec("specfact_cli")
+                if spec:
+                    console.print(f"  - Module spec found: {spec}")
+                    console.print(f"  - Module origin: {spec.origin}")
+                    if spec.origin:
+                        console.print(f"  - Module location: {Path(spec.origin).parent.resolve()}")
+                else:
+                    console.print("  - Module spec: Not found")
+            except Exception as e:
+                console.print(f"  - Error checking module spec: {e}")
+            console.print()
+            console.print("[yellow]Expected location:[/yellow] resources/prompts/")
+            console.print("[yellow]Please ensure SpecFact is properly installed.[/yellow]")
+            raise typer.Exit(1)
+
+        console.print(f"[cyan]Templates:[/cyan] {templates_dir}")
+        console.print()
+
+        # Copy templates to IDE location
+        try:
+            copied_files, settings_path = copy_templates_to_ide(repo_path, detected_ide, templates_dir, force)
+
+            if not copied_files:
+                console.print(
+                    "[yellow]No templates copied (all files already exist, use --force to overwrite)[/yellow]"
+                )
+                record({"files_copied": 0, "already_exists": True})
+                raise typer.Exit(0)
+
+            record(
+                {
+                    "detected_ide": detected_ide,
+                    "files_copied": len(copied_files),
+                    "settings_updated": settings_path is not None,
+                }
+            )
+
+            console.print()
+            console.print(Panel("[bold green]✓ Initialization Complete[/bold green]", border_style="green"))
+            console.print(f"[green]Copied {len(copied_files)} template(s) to {ide_config['folder']}[/green]")
+            if settings_path:
+                console.print(f"[green]Updated VS Code settings:[/green] {settings_path}")
+            console.print()
+            console.print("[dim]You can now use SpecFact slash commands in your IDE![/dim]")
+            console.print("[dim]Example: /specfact-import-from-code --repo . --confidence 0.7[/dim]")
+
+        except Exception as e:
+            console.print(f"[red]Error:[/red] Failed to initialize IDE integration: {e}")
+            raise typer.Exit(1) from e

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/specfact_cli/commands/plan.py

@@ -774,7 +774,11 @@ def update_feature(
     acceptance: str | None = typer.Option(None, "--acceptance", help="Acceptance criteria (comma-separated)"),
     constraints: str | None = typer.Option(None, "--constraints", help="Constraints (comma-separated)"),
     confidence: float | None = typer.Option(None, "--confidence", help="Confidence score (0.0-1.0)"),
-    draft: bool | None = typer.Option(None, "--draft", help="Mark as draft (true/false)"),
+    draft: bool | None = typer.Option(
+        None,
+        "--draft/--no-draft",
+        help="Mark as draft (use --draft to set True, --no-draft to set False, omit to leave unchanged)",
+    ),
     plan: Path | None = typer.Option(
         None,
         "--plan",

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/specfact_cli/importers/speckit_converter.py

@@ -398,8 +398,8 @@ class SpecKitConverter:
             feature_dir = self.repo_path / "specs" / f"{feature_num:03d}-{feature_name}"
             feature_dir.mkdir(parents=True, exist_ok=True)
 
-            # Generate spec.md
-            spec_content = self._generate_spec_markdown(feature)
+            # Generate spec.md (pass calculated feature_num to avoid recalculation)
+            spec_content = self._generate_spec_markdown(feature, feature_num=feature_num)
             (feature_dir / "spec.md").write_text(spec_content, encoding="utf-8")
 
             # Generate plan.md
@@ -416,14 +416,29 @@ class SpecKitConverter:
 
     @beartype
     @require(lambda feature: isinstance(feature, Feature), "Must be Feature instance")
+    @require(
+        lambda feature_num: feature_num is None or feature_num > 0,
+        "Feature number must be None or positive",
+    )
     @ensure(lambda result: isinstance(result, str), "Must return string")
     @ensure(lambda result: len(result) > 0, "Result must be non-empty")
-    def _generate_spec_markdown(self, feature: Feature) -> str:
-        """Generate Spec-Kit spec.md content from SpecFact feature."""
+    def _generate_spec_markdown(self, feature: Feature, feature_num: int | None = None) -> str:
+        """
+        Generate Spec-Kit spec.md content from SpecFact feature.
+
+        Args:
+            feature: Feature to generate spec for
+            feature_num: Optional pre-calculated feature number (avoids recalculation with fallback)
+        """
         from datetime import datetime
 
         # Extract feature branch from feature key (FEATURE-001 -> 001-feature-name)
-        feature_num = self._extract_feature_number(feature.key)
+        # Use provided feature_num if available, otherwise extract from key (with fallback to 1)
+        if feature_num is None:
+            feature_num = self._extract_feature_number(feature.key)
+            if feature_num == 0:
+                # Fallback: use 1 if no number found (shouldn't happen if called from convert_to_speckit)
+                feature_num = 1
         feature_name = self._to_feature_dir_name(feature.title)
         feature_branch = f"{feature_num:03d}-{feature_name}"
 

{specfact_cli-0.6.4 → specfact_cli-0.6.6}/src/specfact_cli/utils/ide_setup.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import os
 import re
+import site
+import sys
 from pathlib import Path
 from typing import Literal
 
@@ -387,3 +389,164 @@ def create_vscode_settings(repo_path: Path, settings_file: str) -> Path | None:
 
     console.print(f"[green]Updated:[/green] {settings_path}")
     return settings_path
+
+
+@beartype
+@ensure(
+    lambda result: isinstance(result, list) and all(isinstance(p, Path) for p in result), "Must return list of Paths"
+)
+def get_package_installation_locations(package_name: str) -> list[Path]:
+    """
+    Get all possible installation locations for a Python package across different OS and installation types.
+
+    This function searches for package locations in:
+    - User site-packages (per-user installations: ~/.local/lib/python3.X/site-packages)
+    - System site-packages (global installations: /usr/lib/python3.X/site-packages, C:\\Python3X\\Lib\\site-packages)
+    - Virtual environments (venv, conda, etc.)
+    - uvx cache locations (~/.cache/uv/archive-v0/...)
+
+    Args:
+        package_name: Name of the package to locate (e.g., "specfact_cli")
+
+    Returns:
+        List of Path objects representing possible package installation locations
+
+    Examples:
+        >>> locations = get_package_installation_locations("specfact_cli")
+        >>> len(locations) > 0
+        True
+    """
+    locations: list[Path] = []
+
+    # Method 1: Use importlib.util.find_spec() to find the actual installed location
+    try:
+        import importlib.util
+
+        spec = importlib.util.find_spec(package_name)
+        if spec and spec.origin:
+            package_path = Path(spec.origin).parent.resolve()
+            locations.append(package_path)
+    except Exception:
+        pass
+
+    # Method 2: Check all site-packages directories (user + system)
+    try:
+        # User site-packages (per-user installation)
+        # Linux/macOS: ~/.local/lib/python3.X/site-packages
+        # Windows: %APPDATA%\\Python\\Python3X\\site-packages
+        user_site = site.getusersitepackages()
+        if user_site:
+            user_package_path = Path(user_site) / package_name
+            if user_package_path.exists():
+                locations.append(user_package_path.resolve())
+    except Exception:
+        pass
+
+    try:
+        # System site-packages (global installation)
+        # Linux: /usr/lib/python3.X/dist-packages, /usr/local/lib/python3.X/dist-packages
+        # macOS: /Library/Frameworks/Python.framework/Versions/X/lib/pythonX.X/site-packages
+        # Windows: C:\\Python3X\\Lib\\site-packages
+        system_sites = site.getsitepackages()
+        for site_path in system_sites:
+            system_package_path = Path(site_path) / package_name
+            if system_package_path.exists():
+                locations.append(system_package_path.resolve())
+    except Exception:
+        pass
+
+    # Method 3: Check sys.path for additional locations (virtual environments, etc.)
+    for path_str in sys.path:
+        if not path_str or path_str == "":
+            continue
+        try:
+            path = Path(path_str).resolve()
+            if path.exists() and path.is_dir():
+                # Check if package is directly in this path
+                package_path = path / package_name
+                if package_path.exists():
+                    locations.append(package_path.resolve())
+                # Check if this is a site-packages directory
+                if path.name == "site-packages" or "site-packages" in path.parts:
+                    package_path = path / package_name
+                    if package_path.exists():
+                        locations.append(package_path.resolve())
+        except Exception:
+            continue
+
+    # Method 4: Check uvx cache locations (common on Linux/macOS/Windows)
+    # uvx stores packages in cache directories with varying structures
+    if sys.platform != "win32":
+        # Linux/macOS: ~/.cache/uv/archive-v0/.../lib/python3.X/site-packages/
+        uvx_cache_base = Path.home() / ".cache" / "uv" / "archive-v0"
+        if uvx_cache_base.exists():
+            for archive_dir in uvx_cache_base.iterdir():
+                if archive_dir.is_dir():
+                    # Look for site-packages directories (rglob finds all matches)
+                    for site_packages_dir in archive_dir.rglob("site-packages"):
+                        if site_packages_dir.is_dir():
+                            package_path = site_packages_dir / package_name
+                            if package_path.exists():
+                                locations.append(package_path.resolve())
+    else:
+        # Windows: Check %LOCALAPPDATA%\\uv\\cache\\archive-v0\\
+        localappdata = os.environ.get("LOCALAPPDATA")
+        if localappdata:
+            uvx_cache_base = Path(localappdata) / "uv" / "cache" / "archive-v0"
+            if uvx_cache_base.exists():
+                for archive_dir in uvx_cache_base.iterdir():
+                    if archive_dir.is_dir():
+                        # Look for site-packages directories
+                        for site_packages_dir in archive_dir.rglob("site-packages"):
+                            if site_packages_dir.is_dir():
+                                package_path = site_packages_dir / package_name
+                                if package_path.exists():
+                                    locations.append(package_path.resolve())
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_locations: list[Path] = []
+    for loc in locations:
+        loc_str = str(loc)
+        if loc_str not in seen:
+            seen.add(loc_str)
+            unique_locations.append(loc)
+
+    return unique_locations
+
+
+@beartype
+@require(lambda package_name: isinstance(package_name, str) and len(package_name) > 0, "Package name must be non-empty")
+@ensure(
+    lambda result: result is None or (isinstance(result, Path) and result.exists()),
+    "Result must be None or existing Path",
+)
+def find_package_resources_path(package_name: str, resource_subpath: str) -> Path | None:
+    """
+    Find the path to a resource within an installed package.
+
+    Searches across all possible installation locations (user, system, venv, uvx cache)
+    to find the package and then locates the resource subpath.
+
+    Args:
+        package_name: Name of the package (e.g., "specfact_cli")
+        resource_subpath: Subpath within the package (e.g., "resources/prompts")
+
+    Returns:
+        Path to the resource directory if found, None otherwise
+
+    Examples:
+        >>> path = find_package_resources_path("specfact_cli", "resources/prompts")
+        >>> path is None or path.exists()
+        True
+    """
+    # Get all possible package installation locations
+    package_locations = get_package_installation_locations(package_name)
+
+    # Try each location
+    for package_path in package_locations:
+        resource_path = (package_path / resource_subpath).resolve()
+        if resource_path.exists():
+            return resource_path
+
+    return None

specfact_cli-0.6.4/src/specfact_cli/commands/init.py

@@ -1,143 +0,0 @@
-"""
-Init command - Initialize SpecFact for IDE integration.
-
-This module provides the `specfact init` command to copy prompt templates
-to IDE-specific locations for slash command integration.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import typer
-from beartype import beartype
-from icontract import ensure, require
-from rich.console import Console
-from rich.panel import Panel
-
-from specfact_cli.telemetry import telemetry
-from specfact_cli.utils.ide_setup import IDE_CONFIG, copy_templates_to_ide, detect_ide
-
-
-app = typer.Typer(help="Initialize SpecFact for IDE integration")
-console = Console()
-
-
-def _is_valid_repo_path(path: Path) -> bool:
-    """Check if path exists and is a directory."""
-    return path.exists() and path.is_dir()
-
-
-@app.callback(invoke_without_command=True)
-@require(lambda ide: ide in IDE_CONFIG or ide == "auto", "IDE must be valid or 'auto'")
-@require(lambda repo: _is_valid_repo_path(repo), "Repo path must exist and be directory")
-@ensure(lambda result: result is None, "Command should return None")
-@beartype
-def init(
-    ide: str = typer.Option(
-        "auto",
-        "--ide",
-        help="IDE type (auto, cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q)",
-    ),
-    repo: Path = typer.Option(
-        Path("."),
-        "--repo",
-        help="Repository path (default: current directory)",
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-    ),
-    force: bool = typer.Option(
-        False,
-        "--force",
-        help="Overwrite existing files",
-    ),
-) -> None:
-    """
-    Initialize SpecFact for IDE integration.
-
-    Copies prompt templates to IDE-specific locations so slash commands work.
-    This command detects the IDE type (or uses --ide flag) and copies
-    SpecFact prompt templates to the appropriate directory.
-
-    Examples:
-        specfact init                    # Auto-detect IDE
-        specfact init --ide cursor       # Initialize for Cursor
-        specfact init --ide vscode --force  # Overwrite existing files
-        specfact init --repo /path/to/repo --ide copilot
-    """
-    telemetry_metadata = {
-        "ide": ide,
-        "force": force,
-    }
-
-    with telemetry.track_command("init", telemetry_metadata) as record:
-        # Resolve repo path
-        repo_path = repo.resolve()
-
-        # Detect IDE
-        detected_ide = detect_ide(ide)
-        ide_config = IDE_CONFIG[detected_ide]
-        ide_name = ide_config["name"]
-
-        console.print()
-        console.print(Panel("[bold cyan]SpecFact IDE Setup[/bold cyan]", border_style="cyan"))
-        console.print(f"[cyan]Repository:[/cyan] {repo_path}")
-        console.print(f"[cyan]IDE:[/cyan] {ide_name} ({detected_ide})")
-        console.print()
-
-        # Find templates directory
-        # Try relative to project root first (for development)
-        templates_dir = repo_path / "resources" / "prompts"
-        if not templates_dir.exists():
-            # Try relative to installed package (for distribution)
-            import importlib.util
-
-            spec = importlib.util.find_spec("specfact_cli")
-            if spec and spec.origin:
-                package_dir = Path(spec.origin).parent.parent
-                templates_dir = package_dir / "site-packages" / "specfact_cli" / "resources" / "prompts"
-                if not templates_dir.exists():
-                    # Fallback: try resources/prompts in project root
-                    templates_dir = Path(__file__).parent.parent.parent.parent / "resources" / "prompts"
-
-        if not templates_dir.exists():
-            console.print(f"[red]Error:[/red] Templates directory not found: {templates_dir}")
-            console.print("[yellow]Expected location:[/yellow] resources/prompts/")
-            console.print("[yellow]Please ensure SpecFact is properly installed.[/yellow]")
-            raise typer.Exit(1)
-
-        console.print(f"[cyan]Templates:[/cyan] {templates_dir}")
-        console.print()
-
-        # Copy templates to IDE location
-        try:
-            copied_files, settings_path = copy_templates_to_ide(repo_path, detected_ide, templates_dir, force)
-
-            if not copied_files:
-                console.print(
-                    "[yellow]No templates copied (all files already exist, use --force to overwrite)[/yellow]"
-                )
-                record({"files_copied": 0, "already_exists": True})
-                raise typer.Exit(0)
-
-            record(
-                {
-                    "detected_ide": detected_ide,
-                    "files_copied": len(copied_files),
-                    "settings_updated": settings_path is not None,
-                }
-            )
-
-            console.print()
-            console.print(Panel("[bold green]✓ Initialization Complete[/bold green]", border_style="green"))
-            console.print(f"[green]Copied {len(copied_files)} template(s) to {ide_config['folder']}[/green]")
-            if settings_path:
-                console.print(f"[green]Updated VS Code settings:[/green] {settings_path}")
-            console.print()
-            console.print("[dim]You can now use SpecFact slash commands in your IDE![/dim]")
-            console.print("[dim]Example: /specfact-import-from-code --repo . --confidence 0.7[/dim]")
-
-        except Exception as e:
-            console.print(f"[red]Error:[/red] Failed to initialize IDE integration: {e}")
-            raise typer.Exit(1) from e