specfact-cli 0.26.2__tar.gz → 0.26.5__tar.gz

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.2
+Version: 0.26.5
 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.26.2 → specfact_cli-0.26.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.2"
+version = "0.26.5"
 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"

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/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.26.2"
+__version__ = "0.26.5"

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/src/specfact_cli/__init__.py

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

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/src/specfact_cli/adapters/ado.py

@@ -29,7 +29,8 @@ from specfact_cli.models.backlog_item import BacklogItem
 from specfact_cli.models.bridge import BridgeConfig
 from specfact_cli.models.capabilities import ToolCapabilities
 from specfact_cli.models.change import ChangeProposal, ChangeTracking
-from specfact_cli.utils.auth_tokens import get_token
+from specfact_cli.runtime import debug_print
+from specfact_cli.utils.auth_tokens import get_token, set_token
 
 
 console = Console()
@@ -75,10 +76,45 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         elif os.environ.get("AZURE_DEVOPS_TOKEN"):
             self.api_token = os.environ.get("AZURE_DEVOPS_TOKEN")
             self.auth_scheme = "basic"
-        elif stored_token := get_token("azure-devops"):
+        elif stored_token := get_token("azure-devops", allow_expired=False):
+            # Valid, non-expired token found
             self.api_token = stored_token.get("access_token")
             token_type = (stored_token.get("token_type") or "bearer").lower()
             self.auth_scheme = "bearer" if token_type == "bearer" else "basic"
+        elif stored_token_expired := get_token("azure-devops", allow_expired=True):
+            # Token exists but is expired - try to refresh using persistent cache
+            expires_at = stored_token_expired.get("expires_at", "unknown")
+            token_type = (stored_token_expired.get("token_type") or "bearer").lower()
+            if token_type == "bearer":
+                # OAuth token expired - try automatic refresh using persistent cache (like Azure CLI)
+                refreshed_token = self._try_refresh_oauth_token()
+                if refreshed_token:
+                    self.api_token = refreshed_token.get("access_token")
+                    self.auth_scheme = "bearer"
+                    # Update stored token with refreshed token
+                    set_token("azure-devops", refreshed_token)
+                    debug_print(f"[dim]OAuth token automatically refreshed (was expired at {expires_at})[/dim]")
+                else:
+                    # Refresh failed - provide helpful guidance
+                    console.print(
+                        f"[yellow]⚠[/yellow] Stored OAuth token expired at {expires_at}. "
+                        "Attempting automatic refresh..."
+                    )
+                    console.print("[yellow]⚠[/yellow] Automatic refresh failed. OAuth tokens expire after ~1 hour.")
+                    console.print(
+                        "[dim]Options:[/dim]\n"
+                        "  1. Use a Personal Access Token (PAT) with longer expiration (up to 1 year):\n"
+                        "     - Create PAT: https://dev.azure.com/{org}/_usersSettings/tokens\n"
+                        "     - Store PAT: specfact auth azure-devops --pat your_pat_token\n"
+                        "  2. Re-authenticate: specfact auth azure-devops\n"
+                        "  3. Use --ado-token option with a valid token"
+                    )
+                    self.api_token = None
+                    self.auth_scheme = None
+            else:
+                # PAT token - no expiration tracking, assume still valid
+                self.api_token = stored_token_expired.get("access_token")
+                self.auth_scheme = "basic"
         else:
             self.api_token = None
             self.auth_scheme = None
@@ -117,8 +153,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             Full URL with proper format based on cloud vs on-premise
 
         Note:
-            For on-premise, if base_url already includes /tfs/{collection} or /{collection},
-            it won't add org again. For cloud, always adds {org}/{project}.
+            For project-based permissions in larger organizations, org must be part of the
+            _apis URL path before the project. This ensures proper permission scoping.
+            Format: {base_url}/{org}/{project}/_apis/...
         """
         if not self.project:
             raise ValueError(f"project required to build ADO URL (project={self.project!r})")
@@ -150,8 +187,16 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             has_collection_in_base = has_tfs or len(parts) > 1
 
             if has_collection_in_base:
-                # Collection already in base_url, just add project
-                url = f"{base_url_normalized}/{self.project}/{path_normalized}?api-version={api_version}"
+                # Collection already in base_url, but for project-based permissions, we still need org in path
+                # Include org before project to ensure proper permission scoping
+                if self.org:
+                    url = f"{base_url_normalized}/{self.org}/{self.project}/{path_normalized}?api-version={api_version}"
+                else:
+                    # Fallback: if org not provided but collection in base_url, use project directly
+                    console.print(
+                        "[yellow]Warning:[/yellow] Collection in base_url but org not provided. Using project directly."
+                    )
+                    url = f"{base_url_normalized}/{self.project}/{path_normalized}?api-version={api_version}"
             elif self.org:
                 # Collection not in base_url, need to add it
                 # For on-premise, typically use /tfs/{collection} format unless explicitly newer format
@@ -1199,6 +1244,62 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return base64.b64encode(f":{token}".encode()).decode()
 
+    def _try_refresh_oauth_token(self) -> dict[str, Any] | None:
+        """
+        Attempt to refresh expired OAuth token using persistent token cache.
+
+        This uses the same persistent cache as the auth command, allowing automatic
+        token refresh without user interaction (like Azure CLI).
+
+        Returns:
+            Refreshed token data dict if successful, None if refresh failed
+        """
+        try:
+            from azure.identity import (  # type: ignore[reportMissingImports]
+                DeviceCodeCredential,
+                TokenCachePersistenceOptions,
+            )
+
+            # Use the same cache name as auth command for shared cache
+            # Try encrypted first, fall back to unencrypted if libsecret unavailable
+            cache_options = None
+            try:
+                try:
+                    cache_options = TokenCachePersistenceOptions(
+                        name="specfact-azure-devops",
+                        allow_unencrypted_cache=False,  # Prefer encrypted
+                    )
+                except Exception:
+                    # Encrypted cache not available, try unencrypted
+                    cache_options = TokenCachePersistenceOptions(
+                        name="specfact-azure-devops",
+                        allow_unencrypted_cache=True,  # Fallback: unencrypted
+                    )
+            except Exception:
+                # Persistent cache completely unavailable, can't refresh
+                return None
+
+            # Create credential with same cache - it will use cached refresh token
+            credential = DeviceCodeCredential(cache_persistence_options=cache_options)
+            # Use the same resource as auth command
+            azure_devops_resource = "499b84ac-1321-427f-aa17-267ca6975798/.default"
+            token = credential.get_token(azure_devops_resource)
+
+            # Return refreshed token data
+            from datetime import UTC, datetime
+
+            expires_at = datetime.fromtimestamp(token.expires_on, tz=UTC).isoformat()
+            return {
+                "access_token": token.token,
+                "token_type": "bearer",
+                "expires_at": expires_at,
+                "resource": azure_devops_resource,
+                "issued_at": datetime.now(tz=UTC).isoformat(),
+            }
+        except Exception:
+            # Refresh failed (no cached refresh token, refresh token expired, etc.)
+            return None
+
     def _auth_headers(self) -> dict[str, str]:
         """Return authorization headers based on token type."""
         if not self.api_token:
@@ -2306,11 +2407,26 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Uses ADO Work Items API to query work items.
         """
         if not self.api_token:
-            msg = "Azure DevOps API token required to fetch backlog items"
+            msg = (
+                "Azure DevOps API token required to fetch backlog items.\n"
+                "Options:\n"
+                "  1. Set AZURE_DEVOPS_TOKEN environment variable\n"
+                "  2. Use --ado-token option\n"
+                "  3. Store token via specfact auth azure-devops"
+            )
             raise ValueError(msg)
 
-        if not self.org or not self.project:
-            msg = "org and project required to fetch backlog items"
+        if not self.org:
+            msg = (
+                "org (organization) required to fetch backlog items.\n"
+                "For Azure DevOps Services (cloud), org is always required.\n"
+                "For Azure DevOps Server (on-premise), org is the collection name.\n"
+                "Provide via --ado-org option or ensure it's set in adapter configuration."
+            )
+            raise ValueError(msg)
+
+        if not self.project:
+            msg = "project required to fetch backlog items. Provide via --ado-project option."
             raise ValueError(msg)
 
         # Build WIQL (Work Item Query Language) query
@@ -2344,14 +2460,23 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # POST to project-level endpoint: {org}/{project}/_apis/wit/wiql?api-version=7.1
         url = self._build_ado_url("_apis/wit/wiql", api_version="7.1")
         headers = {
-            "Authorization": f"{self.auth_scheme} {self.api_token}" if self.auth_scheme else f"Basic {self.api_token}",
+            **self._auth_headers(),
             "Content-Type": "application/json",
             "Accept": "application/json",
         }
         payload = {"query": wiql}
 
-        # Debug: Log URL construction for troubleshooting
-        console.print(f"[dim]ADO WIQL URL: {url}[/dim]")
+        # Debug: Log URL construction and auth status for troubleshooting
+        debug_print(f"[dim]ADO WIQL URL: {url}[/dim]")
+        if "Authorization" in headers:
+            auth_header_preview = (
+                headers["Authorization"][:20] + "..."
+                if len(headers["Authorization"]) > 20
+                else headers["Authorization"]
+            )
+            debug_print(f"[dim]ADO Auth: {auth_header_preview}[/dim]")
+        else:
+            debug_print("[yellow]Warning: No Authorization header in request[/yellow]")
 
         try:
             response = requests.post(url, headers=headers, json=payload, timeout=30)
@@ -2430,14 +2555,12 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
             # Headers for work items batch GET (organization-level endpoint)
             workitems_headers = {
-                "Authorization": f"{self.auth_scheme} {self.api_token}"
-                if self.auth_scheme
-                else f"Basic {self.api_token}",
+                **self._auth_headers(),
                 "Accept": "application/json",
             }
 
             # Debug: Log URL construction for troubleshooting
-            console.print(f"[dim]ADO WorkItems URL: {url}&ids={ids_str}[/dim]")
+            debug_print(f"[dim]ADO WorkItems URL: {url}&ids={ids_str}[/dim]")
 
             try:
                 response = requests.get(url, headers=workitems_headers, params=params, timeout=30)
@@ -2545,7 +2668,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         work_item_id = int(item.id)
         url = self._build_ado_url(f"_apis/wit/workitems/{work_item_id}", api_version="7.1")
         headers = {
-            "Authorization": f"{self.auth_scheme} {self.api_token}" if self.auth_scheme else f"Basic {self.api_token}",
+            **self._auth_headers(),
             "Content-Type": "application/json-patch+json",
         }
 

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/src/specfact_cli/cli.py

@@ -73,7 +73,7 @@ from specfact_cli.commands import (
     validate,
 )
 from specfact_cli.modes import OperationalMode, detect_mode
-from specfact_cli.runtime import get_configured_console
+from specfact_cli.runtime import get_configured_console, set_debug_mode
 from specfact_cli.utils.progressive_disclosure import ProgressiveDisclosureGroup
 from specfact_cli.utils.structured_io import StructuredFormat
 
@@ -236,6 +236,11 @@ def main(
         callback=mode_callback,
         help="Operational mode: cicd (fast, deterministic) or copilot (enhanced, interactive)",
     ),
+    debug: bool = typer.Option(
+        False,
+        "--debug",
+        help="Enable debug output (shows detailed logging and diagnostic information)",
+    ),
     input_format: Annotated[
         StructuredFormat,
         typer.Option(
@@ -278,6 +283,9 @@ def main(
     # Set banner flag based on --no-banner option
     _show_banner = not no_banner
 
+    # Set debug mode
+    set_debug_mode(debug)
+
     runtime.configure_io_formats(input_format=input_format, output_format=output_format)
     # Invert logic: --interactive means not non-interactive, --no-interactive means non-interactive
     if interaction is not None:

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/src/specfact_cli/commands/auth.py

@@ -153,10 +153,54 @@ def _poll_github_device_token(
 
 
 @app.command("azure-devops")
-def auth_azure_devops() -> None:
-    """Authenticate to Azure DevOps using device code flow."""
+def auth_azure_devops(
+    pat: str | None = typer.Option(
+        None,
+        "--pat",
+        help="Store a Personal Access Token (PAT) directly. PATs can have expiration up to 1 year, "
+        "unlike OAuth tokens which expire after ~1 hour. Create PAT at: "
+        "https://dev.azure.com/{org}/_usersSettings/tokens",
+    ),
+    use_device_code: bool = typer.Option(
+        False,
+        "--use-device-code",
+        help="Force device code flow instead of trying interactive browser first. "
+        "Useful for SSH/headless environments where browser cannot be opened.",
+    ),
+) -> None:
+    """
+    Authenticate to Azure DevOps using OAuth (device code or interactive browser) or Personal Access Token (PAT).
+
+    **Token Options:**
+
+    1. **Personal Access Token (PAT)** - Recommended for long-lived authentication:
+       - Use --pat option to store a PAT directly
+       - PATs can have expiration up to 1 year (maximum allowed)
+       - Create PAT at: https://dev.azure.com/{org}/_usersSettings/tokens
+       - Select required scopes (e.g., "Work Items: Read & Write")
+       - Example: specfact auth azure-devops --pat your_pat_token
+
+    2. **OAuth Flow** (default, when no PAT provided):
+       - **First tries interactive browser** (opens browser automatically, better UX)
+       - **Falls back to device code** if browser unavailable (SSH/headless environments)
+       - Access tokens expire after ~1 hour, refresh tokens last 90 days
+       - Automatic token refresh via persistent cache (no re-authentication needed)
+       - Example: specfact auth azure-devops
+
+    3. **Force Device Code Flow** (--use-device-code):
+       - Skip interactive browser, use device code directly
+       - Useful for SSH/headless environments or when browser cannot be opened
+       - Example: specfact auth azure-devops --use-device-code
+
+    **For Long-Lived Tokens:**
+    Use a PAT with 90 days or 1 year expiration instead of OAuth tokens to avoid
+    frequent re-authentication. PATs are stored securely and work the same way as OAuth tokens.
+    """
     try:
-        from azure.identity import DeviceCodeCredential  # type: ignore[reportMissingImports]
+        from azure.identity import (  # type: ignore[reportMissingImports]
+            DeviceCodeCredential,
+            InteractiveBrowserCredential,
+        )
     except ImportError:
         console.print("[bold red]✗[/bold red] azure-identity is not installed.")
         console.print("Install dependencies with: pip install specfact-cli")
@@ -171,9 +215,145 @@ def auth_azure_devops() -> None:
         console.print(f"Enter the code: [bold]{user_code}[/bold]")
         console.print(f"Code expires at: {expires_at.isoformat()}")
 
-    console.print("[bold]Starting Azure DevOps device code authentication...[/bold]")
-    credential = DeviceCodeCredential(prompt_callback=prompt_callback)
-    token = credential.get_token(AZURE_DEVOPS_RESOURCE)
+    # If PAT is provided, store it directly (no expiration for PATs stored as Basic auth)
+    if pat:
+        console.print("[bold]Storing Personal Access Token (PAT)...[/bold]")
+        # PATs are stored as Basic auth tokens (no expiration date set by default)
+        # Users can create PATs with up to 1 year expiration in Azure DevOps UI
+        token_data = {
+            "access_token": pat,
+            "token_type": "basic",  # PATs use Basic authentication
+            "issued_at": datetime.now(tz=UTC).isoformat(),
+            # Note: PAT expiration is managed by Azure DevOps, not stored locally
+            # Users should set expiration when creating PAT (up to 1 year)
+        }
+        set_token("azure-devops", token_data)
+        console.print("[bold green]✓[/bold green] Personal Access Token stored")
+        console.print(
+            "[dim]PAT stored successfully. PATs can have expiration up to 1 year when created in Azure DevOps.[/dim]"
+        )
+        console.print("[dim]Create/manage PATs at: https://dev.azure.com/{org}/_usersSettings/tokens[/dim]")
+        return
+
+    # OAuth flow with persistent token cache (automatic refresh)
+    # Try interactive browser first, fall back to device code if it fails
+    console.print("[bold]Starting Azure DevOps OAuth authentication...[/bold]")
+
+    # Enable persistent token cache for automatic token refresh (like Azure CLI)
+    # This allows tokens to be refreshed automatically without re-authentication
+    cache_options = None
+    use_unencrypted_cache = False
+    try:
+        from azure.identity import TokenCachePersistenceOptions  # type: ignore[reportMissingImports]
+
+        # Try encrypted cache first (secure), fall back to unencrypted if libsecret unavailable
+        try:
+            cache_options = TokenCachePersistenceOptions(
+                name="specfact-azure-devops",  # Shared cache name across processes
+                allow_unencrypted_cache=False,  # Prefer encrypted storage
+            )
+            console.print(
+                "[dim]Persistent token cache enabled (encrypted) - tokens will refresh automatically (like Azure CLI)[/dim]"
+            )
+        except Exception:
+            # Encrypted cache not available (e.g., libsecret missing on Linux), try unencrypted
+            try:
+                cache_options = TokenCachePersistenceOptions(
+                    name="specfact-azure-devops",
+                    allow_unencrypted_cache=True,  # Fallback: unencrypted storage
+                )
+                use_unencrypted_cache = True
+                console.print(
+                    "[yellow]Note:[/yellow] Using unencrypted token cache (libsecret unavailable). "
+                    "Tokens will refresh automatically but stored without encryption."
+                )
+            except Exception:
+                # Persistent cache completely unavailable, use in-memory only
+                console.print(
+                    "[yellow]Note:[/yellow] Persistent cache not available, using in-memory cache only. "
+                    "Tokens will need to be refreshed manually after ~1 hour."
+                )
+    except ImportError:
+        # TokenCachePersistenceOptions not available in this version
+        pass
+
+    # Helper function to try authentication with fallback to unencrypted cache or no cache
+    def try_authenticate_with_fallback(credential_class, credential_kwargs):
+        """Try authentication, falling back to unencrypted cache or no cache if encrypted cache fails."""
+        nonlocal cache_options, use_unencrypted_cache
+        # First try with current cache_options
+        try:
+            credential = credential_class(cache_persistence_options=cache_options, **credential_kwargs)
+            return credential.get_token(AZURE_DEVOPS_RESOURCE)
+        except Exception as e:
+            error_msg = str(e).lower()
+            # Check if error is about cache encryption and we haven't already tried unencrypted
+            if (
+                ("cache encryption" in error_msg or "libsecret" in error_msg)
+                and cache_options
+                and not use_unencrypted_cache
+            ):
+                # Try again with unencrypted cache
+                console.print("[yellow]Note:[/yellow] Encrypted cache unavailable, trying unencrypted cache...")
+                try:
+                    from azure.identity import TokenCachePersistenceOptions  # type: ignore[reportMissingImports]
+
+                    unencrypted_cache = TokenCachePersistenceOptions(
+                        name="specfact-azure-devops",
+                        allow_unencrypted_cache=True,
+                    )
+                    credential = credential_class(cache_persistence_options=unencrypted_cache, **credential_kwargs)
+                    token = credential.get_token(AZURE_DEVOPS_RESOURCE)
+                    console.print(
+                        "[yellow]Note:[/yellow] Using unencrypted token cache (libsecret unavailable). "
+                        "Tokens will refresh automatically but stored without encryption."
+                    )
+                    # Update global cache_options for future use
+                    cache_options = unencrypted_cache
+                    use_unencrypted_cache = True
+                    return token
+                except Exception as e2:
+                    # Unencrypted cache also failed - check if it's the same error
+                    error_msg2 = str(e2).lower()
+                    if "cache encryption" in error_msg2 or "libsecret" in error_msg2:
+                        # Still failing on cache, try without cache entirely
+                        console.print("[yellow]Note:[/yellow] Persistent cache unavailable, trying without cache...")
+                        try:
+                            credential = credential_class(**credential_kwargs)
+                            token = credential.get_token(AZURE_DEVOPS_RESOURCE)
+                            console.print(
+                                "[yellow]Note:[/yellow] Using in-memory cache only. "
+                                "Tokens will need to be refreshed manually after ~1 hour."
+                            )
+                            return token
+                        except Exception:
+                            # Even without cache it failed, re-raise original
+                            raise e from e2
+                    # Different error, re-raise
+                    raise e2 from e
+            # Not a cache encryption error, re-raise
+            raise
+
+    # Try interactive browser first (better UX), fall back to device code if it fails
+    token = None
+    if not use_device_code:
+        try:
+            console.print("[dim]Trying interactive browser authentication...[/dim]")
+            token = try_authenticate_with_fallback(InteractiveBrowserCredential, {})
+            console.print("[bold green]✓[/bold green] Interactive browser authentication successful")
+        except Exception as e:
+            # Interactive browser failed (no display, headless environment, etc.)
+            console.print(f"[yellow]⚠[/yellow] Interactive browser unavailable: {type(e).__name__}")
+            console.print("[dim]Falling back to device code flow...[/dim]")
+
+    # Use device code flow if interactive browser failed or was explicitly requested
+    if token is None:
+        console.print("[bold]Using device code authentication...[/bold]")
+        try:
+            token = try_authenticate_with_fallback(DeviceCodeCredential, {"prompt_callback": prompt_callback})
+        except Exception as e:
+            console.print(f"[bold red]✗[/bold red] Authentication failed: {e}")
+            raise typer.Exit(1) from e
 
     expires_at = datetime.fromtimestamp(token.expires_on, tz=UTC).isoformat()
     token_data = {
@@ -187,6 +367,10 @@ def auth_azure_devops() -> None:
 
     console.print("[bold green]✓[/bold green] Azure DevOps authentication complete")
     console.print("Stored token for provider: azure-devops")
+    console.print(
+        f"[yellow]⚠[/yellow] Token expires at: {expires_at}\n"
+        "[dim]For longer-lived tokens (up to 1 year), use --pat option with a Personal Access Token.[/dim]"
+    )
 
 
 @app.command("github")

{specfact_cli-0.26.2 → specfact_cli-0.26.5}/src/specfact_cli/commands/init.py

@@ -17,6 +17,7 @@ from icontract import ensure, require
 from rich.console import Console
 from rich.panel import Panel
 
+from specfact_cli.runtime import debug_print
 from specfact_cli.telemetry import telemetry
 from specfact_cli.utils.env_manager import EnvManager, build_tool_command, detect_env_manager
 from specfact_cli.utils.ide_setup import (
@@ -258,12 +259,12 @@ def init(
         # 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}")
+        debug_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...")
+            debug_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
@@ -273,7 +274,7 @@ def init(
             try:
                 import importlib.resources
 
-                console.print("[dim]Debug:[/dim] Using importlib.resources.files() API...")
+                debug_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"
@@ -282,7 +283,7 @@ def init(
                 # 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}")
+                debug_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}")
@@ -292,20 +293,20 @@ def init(
                 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()...")
+                debug_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()...")
+                debug_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()...")
+                debug_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...")
+                    debug_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
@@ -314,8 +315,8 @@ def init(
                         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}")
+                        debug_print(f"[dim]Debug:[/dim] Package root from spec.origin: {package_root}")
+                        debug_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}")
@@ -324,20 +325,20 @@ def init(
                     else:
                         console.print("[yellow]⚠[/yellow] Could not find specfact_cli module spec")
                         if spec is None:
-                            console.print("[dim]Debug:[/dim] spec is None")
+                            debug_print("[dim]Debug:[/dim] spec is None")
                         elif not spec.origin:
-                            console.print("[dim]Debug:[/dim] spec.origin is None or empty")
+                            debug_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...")
+                    debug_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)")
+                    debug_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}")
+                        debug_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)
@@ -347,7 +348,7 @@ def init(
                             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...")
+                        debug_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)
@@ -361,15 +362,15 @@ def init(
             # 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__...")
+                    debug_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}")
+                    debug_print(f"[dim]Debug:[/dim] Current file: {current_file}")
+                    debug_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}")