specfact-cli 0.46.19__tar.gz → 0.46.28__tar.gz

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.46.19
+Version: 0.46.28
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -224,6 +224,7 @@ Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.11
 Requires-Dist: azure-identity>=1.17.1
 Requires-Dist: beartype>=0.22.4
+Requires-Dist: click<8.2,>=8.1.8
 Requires-Dist: commentjson>=0.9.0
 Requires-Dist: cryptography>=43.0.0
 Requires-Dist: gitpython>=3.1.45
@@ -232,14 +233,12 @@ Requires-Dist: icontract>=2.7.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: networkx>=3.4.2
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
-Requires-Dist: opentelemetry-sdk>=1.27.0
 Requires-Dist: packaging>=24.0
 Requires-Dist: pydantic>=2.12.3
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: questionary>=2.0.1
 Requires-Dist: requests>=2.32.3
-Requires-Dist: rich<13.6.0,>=13.5.2
+Requires-Dist: rich<16.0.0,>=13.5.2
 Requires-Dist: ruamel-yaml>=0.18.16
 Requires-Dist: typer<0.24,>=0.20.0
 Requires-Dist: typing-extensions>=4.15.0
@@ -277,6 +276,9 @@ Requires-Dist: graphviz>=0.20.1; extra == 'enhanced-analysis'
 Requires-Dist: pycg==0.0.7; extra == 'enhanced-analysis'
 Provides-Extra: scanning
 Requires-Dist: semgrep>=1.144.0; extra == 'scanning'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'telemetry'
 Description-Content-Type: text/markdown
 
 # SpecFact CLI
@@ -340,6 +342,8 @@ specfact code review run --path . --scope full
 
 The sample output comes from a pinned capture against `nold-ai/specfact-demo-repo`. Reproduce it with `docs/_support/readme-first-contact/capture-readme-output.sh`; capture metadata lives alongside the raw logs in `docs/_support/readme-first-contact/sample-output/`.
 
+The Code Review bundle also reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies, such as redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, and avoidable intermediate lists. These findings are advisory, score-neutral, and not AI-authorship detection. Use the generated `.specfact/code-review.json` report with the Project bundle's `/specfact.08-simplify` IDE prompt to review each cleanup before accepting it. See the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+
 ## What SpecFact does
 
 - **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/README.md

@@ -59,6 +59,8 @@ specfact code review run --path . --scope full
 
 The sample output comes from a pinned capture against `nold-ai/specfact-demo-repo`. Reproduce it with `docs/_support/readme-first-contact/capture-readme-output.sh`; capture metadata lives alongside the raw logs in `docs/_support/readme-first-contact/sample-output/`.
 
+The Code Review bundle also reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies, such as redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, and avoidable intermediate lists. These findings are advisory, score-neutral, and not AI-authorship detection. Use the generated `.specfact/code-review.json` report with the Project bundle's `/specfact.08-simplify` IDE prompt to review each cleanup before accepting it. See the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+
 ## What SpecFact does
 
 - **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.46.19"
+version = "0.46.28"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -65,8 +65,9 @@ dependencies = [
 
     # CLI framework
     # Typer 0.24+ requires click>=8.2.1 (generic Choice[...]); dev semgrep pins click~=8.1.8 — cap Typer.
+    "click>=8.1.8,<8.2",
     "typer>=0.20.0,<0.24",
-    "rich>=13.5.2,<13.6.0",  # Compatible with semgrep (requires rich~=13.5.2)
+    "rich>=13.5.2,<16.0.0",  # Semgrep allows rich>=13.5.2; keep below next major.
     "questionary>=2.0.1",  # Interactive prompts with arrow key navigation
     
     # Template engine
@@ -94,10 +95,6 @@ dependencies = [
 
     # File system watching
     "watchdog>=6.0.0",
-
-    # Telemetry (opt-in; only active when SPECFACT_TELEMETRY_OPT_IN=true)
-    "opentelemetry-sdk>=1.27.0",
-    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
 ]
 
 [project.optional-dependencies]
@@ -106,6 +103,11 @@ contracts = [
     "hypothesis>=6.142.4",
 ]
 
+telemetry = [
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
 dev = [
     "setuptools>=69.0.0,<82",
     "pytest>=8.4.2",

specfact_cli-0.46.28/resources/bundled-module-registry/index.json

@@ -0,0 +1,26 @@
+{
+  "modules": [
+    {
+      "checksum_sha256": "ce82ea7d2a48dfa8b16ad48599ec6daa922d6aa1a61c242da1143366d5d53ec4",
+      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/init-0.1.33.tar.gz",
+      "id": "init",
+      "latest_version": "0.1.33"
+    },
+    {
+      "checksum_sha256": "49c5bcbef6ce4aba3302b8209d3641cc34430f3fe4754423d61428557f8c641d",
+      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/upgrade-0.1.19.tar.gz",
+      "id": "upgrade",
+      "latest_version": "0.1.19"
+    },
+    {
+      "checksum_sha256": "79359da27cb1c734a928a453a786b626e7b06654f515f32ead0cf96fa8e70bc2",
+      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/module-registry-0.1.26.tar.gz",
+      "id": "module-registry",
+      "latest_version": "0.1.26"
+    },
+    {
+      "id": "bundle-mapper",
+      "latest_version": "0.1.9"
+    }
+  ]
+}

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.46.19"
+__version__ = "0.46.28"

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/__init__.py

@@ -45,6 +45,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.46.19"
+__version__ = "0.46.28"
 
 __all__ = ["__version__"]

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/adapters/ado.py

@@ -1625,7 +1625,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         headers = {"Content-Type": "application/json-patch+json", **self._auth_headers()}
         try:
             response = self._request_with_retry(
-                lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30)
+                lambda: requests.patch(url, json=cast(Any, patch_document), headers=headers, timeout=30)
             )
         except requests.RequestException as exc:
             resp = getattr(exc, "response", None)
@@ -1939,7 +1939,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             # Refresh failed (no cached refresh token, refresh token expired, etc.)
             return None
 
-    def _auth_headers(self) -> dict[str, str]:
+    def _auth_headers(self) -> dict[str, str | bytes]:
         """Return authorization headers based on token type."""
         if not self.api_token:
             return {}
@@ -1953,7 +1953,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         self,
         url: str,
         *,
-        headers: dict[str, str] | None = None,
+        headers: dict[str, str | bytes] | None = None,
         params: dict[str, Any] | None = None,
         timeout: int = 30,
         retry_on_ambiguous_transport: bool = True,
@@ -1973,7 +1973,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         self,
         url: str,
         *,
-        headers: dict[str, str] | None = None,
+        headers: dict[str, str | bytes] | None = None,
         params: dict[str, Any] | None = None,
         json: dict[str, Any] | None = None,
         timeout: int = 30,
@@ -2213,7 +2213,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         try:
             response = self._request_with_retry(
-                lambda: requests.post(url, json=patch_document, headers=headers, timeout=30),
+                lambda: requests.post(url, json=cast(Any, patch_document), headers=headers, timeout=30),
                 retry_on_ambiguous_transport=False,
             )
             if is_debug_mode():
@@ -2670,7 +2670,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         try:
             response = self._request_with_retry(
-                lambda: requests.post(url, json=comment_body, headers=headers, timeout=30),
+                lambda: requests.post(url, json=cast(Any, comment_body), headers=headers, timeout=30),
                 retry_on_ambiguous_transport=False,
             )
             comment_data = response.json()
@@ -3478,7 +3478,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             **self._auth_headers(),
         }
         response = self._request_with_retry(
-            lambda: requests.post(url, json=patch_document, headers=headers, timeout=30),
+            lambda: requests.post(url, json=cast(Any, patch_document), headers=headers, timeout=30),
             retry_on_ambiguous_transport=False,
         )
         created = response.json()
@@ -3782,7 +3782,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         if operations_no_format == operations:
             return None
         try:
-            resp = requests.patch(url, headers=headers, json=operations_no_format, timeout=30)
+            resp = requests.patch(url, headers=headers, json=cast(Any, operations_no_format), timeout=30)
             resp.raise_for_status()
             return resp
         except requests.HTTPError as retry_error:
@@ -3802,7 +3802,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
     ) -> requests.Response | None:
         operations_replace = self._backlog_ops_replace_multiline_add_with_replace(operations)
         try:
-            resp = requests.patch(url, headers=headers, json=operations_replace, timeout=30)
+            resp = requests.patch(url, headers=headers, json=cast(Any, operations_replace), timeout=30)
             resp.raise_for_status()
             return resp
         except requests.HTTPError:
@@ -3820,7 +3820,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         )
         operations_html = self._backlog_ops_convert_markdown_fields_to_html(operations)
         try:
-            resp = requests.patch(url, headers=headers, json=operations_html, timeout=30)
+            resp = requests.patch(url, headers=headers, json=cast(Any, operations_html), timeout=30)
             resp.raise_for_status()
             return resp
         except requests.HTTPError:
@@ -3834,7 +3834,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         operations: list[dict[str, Any]],
     ) -> requests.Response:
         try:
-            return self._request_with_retry(lambda: requests.patch(url, headers=headers, json=operations, timeout=30))
+            return self._request_with_retry(
+                lambda: requests.patch(url, headers=headers, json=cast(Any, operations), timeout=30)
+            )
         except requests.HTTPError as e:
             user_msg = _log_ado_patch_failure(e.response, operations, url)
             e.ado_user_message = user_msg  # type: ignore[attr-defined]

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/adapters/github.py

@@ -561,7 +561,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         from specfact_cli.backlog.converter import convert_github_issue_to_backlog_item
 
         url = f"{self.base_url}/search/issues"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1232,7 +1232,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         repo_owner, repo_name, issue_number = self._parse_issue_reference(item_ref)
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1498,7 +1498,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Create issue via GitHub API
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1592,7 +1592,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Update issue state
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1601,7 +1601,9 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             payload["state_reason"] = state_reason
 
         try:
-            response = self._request_with_retry(lambda: requests.patch(url, json=payload, headers=headers, timeout=30))
+            response = self._request_with_retry(
+                lambda: requests.patch(url, json=cast(Any, payload), headers=headers, timeout=30)
+            )
             issue_data = response.json()
 
             # Add comment explaining status change
@@ -1634,7 +1636,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             return []
 
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}/comments"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1658,7 +1660,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             comment: Comment text
         """
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}/comments"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1666,7 +1668,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         try:
             self._request_with_retry(
-                lambda: requests.post(url, json=payload, headers=headers, timeout=30),
+                lambda: requests.post(url, json=cast(Any, payload), headers=headers, timeout=30),
                 retry_on_ambiguous_transport=False,
             )
         except requests.RequestException as e:
@@ -1676,7 +1678,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
     def _fetch_issue_snapshot(self, repo_owner: str, repo_name: str, issue_number: int) -> tuple[str, str, str]:
         """Fetch current issue body, title, and state for preservation-aware updates."""
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1759,7 +1761,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Update issue body via GitHub API PATCH
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1969,7 +1971,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Get current issue to retrieve existing labels
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -1987,7 +1989,9 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             patch_url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}"
             patch_payload = {"labels": all_labels}
 
-            self._request_with_retry(lambda: requests.patch(patch_url, json=patch_payload, headers=headers, timeout=30))
+            self._request_with_retry(
+                lambda: requests.patch(patch_url, json=cast(Any, patch_payload), headers=headers, timeout=30)
+            )
 
             return {
                 "issue_number": current_issue.get("number", issue_number),  # Use API response number (int)
@@ -2623,7 +2627,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             return None
 
         url = f"{self.base_url}/repos/{self.repo_owner}/{self.repo_name}/issues/{normalized_id}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
@@ -2761,7 +2765,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
     @beartype
     def _github_graphql(self, query: str, variables: dict[str, Any]) -> dict[str, Any]:
         """Execute GitHub GraphQL request and return `data` payload."""
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github+json",
         }
@@ -2976,14 +2980,14 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             issue_type, str(payload.get("priority") or "").strip(), payload.get("story_points")
         )
         url = f"{self.base_url}/repos/{owner}/{repo}/issues"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }
         response = self._request_with_retry(
             lambda: requests.post(
                 url,
-                json={"title": title, "body": body, "labels": labels},
+                json=cast(Any, {"title": title, "body": body, "labels": labels}),
                 headers=headers,
                 timeout=30,
             ),
@@ -3245,7 +3249,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         issue_number = int(item.id)
         url = f"{self.base_url}/repos/{self.repo_owner}/{self.repo_name}/issues/{issue_number}"
-        headers = {
+        headers: dict[str, str | bytes] = {
             "Authorization": f"token {self.api_token}",
             "Accept": "application/vnd.github.v3+json",
         }

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/cli.py

@@ -698,6 +698,8 @@ class _LazyDelegateGroup(click.Group):
         real_group = self._get_real_click_group()
         if real_group is not None:
             return real_group.get_command(ctx, cmd_name)
+        if self._lazy_cmd_name in KNOWN_BUNDLE_GROUP_OR_SHIM_NAMES:
+            return self._delegate_cmd
         return None
 
     def _get_real_click_group(self) -> click.Group | None:

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/models/project.py

@@ -662,7 +662,13 @@ class ProjectBundle(BaseModel):
         if progress_callback:
             progress_callback(total_artifacts, total_artifacts, "bundle.manifest.yaml")
         manifest_path = bundle_dir / "bundle.manifest.yaml"
-        dump_structured_file(self.manifest.model_dump(mode="json"), manifest_path)
+        manifest_data = self.manifest.model_dump(mode="json")
+        if num_features > 1000:
+            import json
+
+            manifest_path.write_text(json.dumps(manifest_data, indent=2), encoding="utf-8")
+        else:
+            dump_structured_file(manifest_data, manifest_path)
 
     @beartype
     @require(lambda self, key: isinstance(key, str) and len(key) > 0, "Feature key must be non-empty string")

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/modules/module_registry/module-package.yaml

@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.24
+version: 0.1.26
 commands:
   - module
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: 'Manage modules: search, list, show, install, and upgrade.'
 license: Apache-2.0
 integrity:
-  checksum: sha256:bc1293efa20676657f440f5c8f21583fcf7c5c2138d754e0262934417c92cfbb
-  signature: 7hALhs1hTjtnz3SdYmzKIqoniyvJDk5LyFcauv/wnVJRyZEQyPv42sb0Zk30zXAZ8QPE/g43/g4l78nv0AqNBQ==
+  checksum: sha256:52a65869fb3d2d36910308c954e0ba199cb1c73f24136ee0d4aa7254f0996a22
+  signature: Uo2eJ40HiWBqe77N8gjiDg7zGhsvJE/hN82+Jcto7yUoqbH7bidLw9DfVQ0CrJfgM9Y0XHAUS1+LMyPr1jAaBg==

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/modules/module_registry/src/commands.py

@@ -28,7 +28,12 @@ from specfact_cli.registry.alias_manager import create_alias, list_aliases, remo
 from specfact_cli.registry.custom_registries import add_registry, fetch_all_indexes, list_registries, remove_registry
 from specfact_cli.registry.help_cache import run_discovery_and_write_cache
 from specfact_cli.registry.marketplace_client import fetch_registry_index
-from specfact_cli.registry.module_discovery import discover_all_modules, discover_all_modules_for_project
+from specfact_cli.registry.module_discovery import (
+    DiscoveredModule,
+    discover_all_modules,
+    discover_all_modules_for_project,
+    discover_all_modules_for_project_with_shadowed,
+)
 from specfact_cli.registry.module_installer import (
     REGISTRY_ID_FILE,
     USER_MODULES_ROOT,
@@ -1066,6 +1071,107 @@ def _print_bundled_available_table(available: list[ModulePackageMetadata]) -> No
     console.print("[dim]Install bundled modules into project scope: specfact module init --scope project[/dim]")
 
 
+def _doctor_entry_matches(entry: DiscoveredModule, module_id: str | None) -> bool:
+    if module_id is None:
+        return True
+    requested = module_id.strip()
+    if not requested:
+        return True
+    discovered_id = entry.metadata.name
+    if requested == discovered_id:
+        return True
+    if "/" in requested:
+        return False
+    return requested.rsplit("/", 1)[-1] == discovered_id.rsplit("/", 1)[-1]
+
+
+def _doctor_dev_roots() -> list[tuple[str, str]]:
+    roots: list[tuple[str, str]] = []
+    for env_name in ("SPECFACT_MODULES_REPO", "SPECFACT_CLI_MODULES_REPO"):
+        value = os.environ.get(env_name, "").strip()
+        if value:
+            roots.append((env_name, value))
+    for raw_root in os.environ.get("SPECFACT_MODULES_ROOTS", "").split(os.pathsep):
+        value = raw_root.strip()
+        if value:
+            roots.append(("SPECFACT_MODULES_ROOTS", value))
+    return roots
+
+
+def _doctor_status(
+    entry: DiscoveredModule,
+    seen_by_module_id: set[str],
+    enabled_state: dict[str, dict[str, Any]],
+) -> str:
+    module_id = entry.metadata.name
+    if module_id in seen_by_module_id:
+        return "shadowed"
+    seen_by_module_id.add(module_id)
+    if enabled_state.get(module_id, {}).get("enabled", True) is False:
+        return "disabled"
+    return "effective"
+
+
+def _print_doctor_recovery(entries: list[tuple[DiscoveredModule, str]]) -> None:
+    for entry, status in entries:
+        if status != "shadowed" or entry.source != "user":
+            continue
+        console.print(f"[yellow]Recovery:[/yellow] specfact module uninstall {entry.metadata.name} --scope user")
+
+
+@app.command(name="doctor")
+@beartype
+@require(_module_id_optional_nonempty, "module_id must be non-empty if provided")
+def doctor(
+    module_id: str | None = typer.Argument(None, help="Optional module id to inspect"),
+    repo: Path | None = typer.Option(None, "--repo", help="Repository path for project scope (default: current dir)"),
+) -> None:
+    """Diagnose module scope, shadowing, and development source roots."""
+    repo_path = (repo or Path.cwd()).resolve()
+    discovered = [
+        entry
+        for entry in discover_all_modules_for_project_with_shadowed(repo_path)
+        if _doctor_entry_matches(entry, module_id)
+    ]
+    if not discovered:
+        console.print("[yellow]No matching modules discovered.[/yellow]")
+    else:
+        state = read_modules_state()
+        seen_by_module_id: set[str] = set()
+        rows: list[tuple[DiscoveredModule, str]] = []
+        table = Table(title="Module Doctor")
+        table.add_column("Module", style="cyan")
+        table.add_column("Version", style="magenta")
+        table.add_column("Status", style="yellow")
+        table.add_column("Origin", style="blue")
+        table.add_column("Enabled", style="green")
+        table.add_column("Path", overflow="fold")
+        for entry in discovered:
+            status = _doctor_status(entry, seen_by_module_id, state)
+            enabled = state.get(entry.metadata.name, {}).get("enabled", True) is not False
+            rows.append((entry, status))
+            table.add_row(
+                entry.metadata.name,
+                entry.metadata.version,
+                status,
+                entry.source,
+                "yes" if enabled else "no",
+                str(entry.package_dir),
+            )
+        console.print(table)
+        _print_doctor_recovery(rows)
+
+    dev_roots = _doctor_dev_roots()
+    if not dev_roots:
+        return
+    dev_table = Table(title="Development Source Roots")
+    dev_table.add_column("Source", style="cyan")
+    dev_table.add_column("Path", overflow="fold")
+    for source, path in dev_roots:
+        dev_table.add_row(source, path)
+    console.print(dev_table)
+
+
 @app.command(name="list")
 @beartype
 @require(

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/modules/upgrade/module-package.yaml

@@ -1,5 +1,5 @@
 name: upgrade
-version: 0.1.15
+version: 0.1.19
 commands:
   - upgrade
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: Check and apply SpecFact CLI version upgrades.
 license: Apache-2.0
 integrity:
-  checksum: sha256:134da8c48f8be96e9a4337a7cc2076bbf8b19e0d3f69161636bcec050f97e4c1
-  signature: CK8Gq+/d0zWlU1Lo1I6EcgPiT3FzVsXj+CXFn7+zUnpXRdpYZxccLLZqh1Hvl2IPv3Y4yecVlOEcWZKtn0tJBg==
+  checksum: sha256:fda269f874f7b61ad5ec8217ba1550e49b1e2e17b23aafd08b39df1a98d66ee1
+  signature: yx89WfwC8DQUkAw2WD1EdHp08Ug0dFw3gNbIXbwgcdoxUBa9qA/0TaHHNBbyhVIxgL6wb+H4XCbYjdwb6XU1Bg==

{specfact_cli-0.46.19 → specfact_cli-0.46.28}/src/specfact_cli/modules/upgrade/src/commands.py

@@ -23,6 +23,7 @@ from icontract import ensure
 from rich.console import Console
 from rich.panel import Panel
 from rich.prompt import Confirm
+from rich.text import Text
 
 from specfact_cli import __version__
 from specfact_cli.contracts.module_interface import ModuleIOContract
@@ -223,16 +224,27 @@ def _build_upgrade_command(method: InstallationMethod) -> list[str] | None:
 def _execute_upgrade_command(command: list[str]) -> bool:
     try:
         console.print("[cyan]Updating SpecFact CLI...[/cyan]")
-        result = subprocess.run(command, check=False, timeout=300)
-    except subprocess.TimeoutExpired:
+        result = subprocess.run(command, check=False, timeout=300, capture_output=True)
+    except subprocess.TimeoutExpired as exc:
+        _replay_upgrade_output(_coerce_subprocess_output(exc.stdout))
+        _replay_upgrade_output(_coerce_subprocess_output(exc.stderr))
         console.print("[red]✗ Update timed out (exceeded 5 minutes)[/red]")
         return False
     except OSError as e:
         console.print(f"[red]✗ Update failed: {e}[/red]")
         return False
+    stdout = _coerce_subprocess_output(result.stdout)
+    stderr = _coerce_subprocess_output(result.stderr)
     if result.returncode != 0:
+        _replay_upgrade_output(stdout)
+        _replay_upgrade_output(stderr)
         console.print(f"[red]✗ Update failed with exit code {result.returncode}[/red]")
         return False
+    if _is_pipx_upgrade_command(command):
+        stdout = _filter_pipx_spaced_home_warning(stdout)
+        stderr = _filter_pipx_spaced_home_warning(stderr)
+    _replay_upgrade_output(stdout)
+    _replay_upgrade_output(stderr)
     console.print("[green]✓ Update successful![/green]")
     from datetime import datetime
 
@@ -243,6 +255,48 @@ def _execute_upgrade_command(command: list[str]) -> bool:
     return True
 
 
+def _coerce_subprocess_output(output: object) -> str:
+    """Return subprocess output as displayable text."""
+    if isinstance(output, str):
+        return output
+    if isinstance(output, bytes):
+        return output.decode(errors="replace")
+    return ""
+
+
+def _is_pipx_upgrade_command(command: list[str]) -> bool:
+    """Return whether command is the supported pipx upgrade invocation."""
+    return len(command) >= 3 and command[:3] == ["pipx", "upgrade", "specfact-cli"]
+
+
+def _replay_upgrade_output(output: str) -> None:
+    """Replay captured child-process output without Rich markup parsing."""
+    if output:
+        console.print(Text(output), end="")
+
+
+def _filter_pipx_spaced_home_warning(output: str) -> str:
+    """Remove only pipx's known spaced-home warning block from successful output."""
+    if not output:
+        return output
+    warning_markers = (
+        "Found a space in the pipx home path",
+        "To see your PIPX_HOME dir",
+        "Most likely fix on macOS",
+    )
+    filtered_lines: list[str] = []
+    skipping_wrapped_warning = False
+    for line in output.splitlines(keepends=True):
+        if any(marker in line for marker in warning_markers):
+            skipping_wrapped_warning = "Found a space in the pipx home path" in line
+            continue
+        if skipping_wrapped_warning and line[:1].isspace():
+            continue
+        skipping_wrapped_warning = False
+        filtered_lines.append(line)
+    return "".join(filtered_lines)
+
+
 def _upgrade_log_started(check_only: bool, yes: bool) -> None:
     if is_debug_mode():
         debug_log_operation(