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

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/.gitignore

@@ -113,6 +113,7 @@ docs/internal/
 .claude/commands/specfact.*.md
 .claude/skills/openspec-*/
 !.claude/skills/openspec-workflows/
+.claude/settings.json
 
 .codex/skills/openspec-*/
 !.codex/skills/openspec-workflows/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.46.17
+Version: 0.46.19
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.46.17"
+version = "0.46.19"
 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"
@@ -283,6 +283,7 @@ verify-removal-gate = [
     "hatch run verify-modules-signature",
 ]
 export-change-github = "python scripts/export-change-to-github.py {args}"
+runtime-discovery-smoke = "python scripts/runtime_discovery_smoke.py {args}"
 
 # Contract-First Smart Test System Scripts
 contract-test = "python tools/contract_first_smart_test.py run --level auto {args}"

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/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.17"
+__version__ = "0.46.19"

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

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

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

@@ -178,6 +178,11 @@ class _RootCLIGroup(ProgressiveDisclosureGroup):
                 _print_missing_bundle_command_help(invoked)
                 raise SystemExit(1) from None
             raise
+        except ValueError as exc:
+            if invoked in KNOWN_BUNDLE_GROUP_OR_SHIM_NAMES:
+                _print_missing_bundle_command_help(invoked)
+                raise SystemExit(1) from exc
+            raise
         _name, cmd, remaining = result
         if cmd is not None or not remaining:
             return result
@@ -610,6 +615,12 @@ def _strip_redundant_single_command_arg(click_cmd: click.Command, args: tuple[st
     return args_list
 
 
+def _lazy_delegate_remaining_args(ctx: click.Context) -> list[str]:
+    ctx_state = vars(ctx)
+    protected_args = ctx_state.get("_protected_args") or ctx_state.get("protected_args") or ()
+    return [str(arg) for arg in (*protected_args, *ctx.args)]
+
+
 class _LazyDelegateGroup(click.Group):
     """Click Group that delegates all args to the real command (lazy-loaded)."""
 
@@ -657,9 +668,10 @@ class _LazyDelegateGroup(click.Group):
     @require(lambda ctx: ctx is not None, "ctx must not be None")
     @ensure(lambda result: result is None or isinstance(result, int), "result must be None or an exit code")
     def invoke(self, ctx: click.Context) -> Any:
-        if ctx.invoked_subcommand is None and not ctx.args:
+        if ctx.invoked_subcommand is None:
+            args = _lazy_delegate_remaining_args(ctx)
             ctx.meta["original_prog_name"] = ctx.command_path
-            return self._delegate_cmd.main(args=[], prog_name=ctx.command_path, standalone_mode=False)
+            return self._delegate_cmd.main(args=args, prog_name=ctx.command_path, standalone_mode=False)
         return super().invoke(ctx)
 
     @require(_lazy_delegate_cmd_name_ready, "lazy command name must be set")

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/src/specfact_cli/modules/init/module-package.yaml

@@ -1,5 +1,5 @@
 name: init
-version: 0.1.31
+version: 0.1.33
 commands:
   - init
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: Initialize SpecFact workspace and bootstrap local configuration.
 license: Apache-2.0
 integrity:
-  checksum: sha256:0f7bc54a823bea14033fcb143ecb6c83d2bca2b5da661f03a0b545100acebe5b
-  signature: dTatkqgBUtti4tL/pmcFBZY9bsJ61gY/V0lP9gZU8Y5W3YWK+wpgRx1oewlAmfKzkxca2NhalKcjLACQjTNvAA==
+  checksum: sha256:0086a4fa3e1f8744deee21640e73e6e2f24daf2b4a680b9157feed5487afc208
+  signature: L7DtVqvg+zqc/CgJu/mOkvxYpfH9HuddbLS3EK5Uvnf6K/j/BofqopamZDdHVlevOGAb+dbsk06kskNOIJfkDQ==

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/src/specfact_cli/modules/init/src/commands.py

@@ -26,7 +26,13 @@ from specfact_cli.registry.module_state import write_modules_state
 from specfact_cli.runtime import debug_print, is_non_interactive
 from specfact_cli.telemetry import telemetry
 from specfact_cli.utils.contract_predicates import repo_path_exists, repo_path_is_dir
-from specfact_cli.utils.env_manager import EnvManager, EnvManagerInfo, build_tool_command, detect_env_manager
+from specfact_cli.utils.env_manager import (
+    EnvManager,
+    EnvManagerInfo,
+    build_tool_command,
+    detect_env_manager,
+    env_info_from_tool_choice,
+)
 from specfact_cli.utils.ide_setup import (
     IDE_CONFIG,
     PROMPT_SOURCE_CORE,
@@ -610,6 +616,11 @@ def init_ide(
         "--ide",
         help="IDE type (cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q, auto)",
     ),
+    env_manager: EnvManager = typer.Option(
+        EnvManager.AUTO,
+        "--env-manager",
+        help="Environment manager override: auto, uv, hatch, poetry, or pip",
+    ),
     prompts: str | None = typer.Option(
         None,
         "--prompts",
@@ -638,7 +649,17 @@ def init_ide(
     console.print(f"[cyan]IDE:[/cyan] {ide_name} ({selected_ide})")
     console.print()
 
-    env_info = detect_env_manager(repo_path)
+    env_info = (
+        detect_env_manager(repo_path)
+        if env_manager is EnvManager.AUTO
+        else env_info_from_tool_choice(env_manager, repo_path)
+    )
+    if env_manager is not EnvManager.AUTO and not env_info.available:
+        console.print(Panel(f"[bold red]{env_info.message}[/bold red]", border_style="red"))
+        raise typer.Exit(1)
+    if env_info.manager is not EnvManager.UNKNOWN:
+        console.print(f"[cyan]Environment manager:[/cyan] {env_info.manager.value}")
+        console.print()
     if env_info.manager == EnvManager.UNKNOWN:
         console.print(
             Panel(
@@ -673,7 +694,12 @@ def init_ide(
     copied_files, settings_path = copy_templates_to_ide(
         repo_path, selected_ide, force, prompts_by_source=selected_catalog
     )
-    write_ide_prompt_export_state(repo_path, selected_ide, sorted(selected_catalog.keys()))
+    write_ide_prompt_export_state(
+        repo_path,
+        selected_ide,
+        sorted(selected_catalog.keys()),
+        env_manager=env_info.manager.value,
+    )
     _copy_backlog_field_mapping_templates(repo_path, force, console)
 
     console.print()

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

@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.23
+version: 0.1.24
 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:f500281d2249d712be23a1b25b5660374694dfa47634f60ae4378eb2cdb753ca
-  signature: cunuat95bD44IcNUBs35NTlHYOR8atydVz4ZyZTjIzwJL6Wz5YOfBYGq/WtgDnOFv3KplfvhRZbTo3CwmS/KBQ==
+  checksum: sha256:bc1293efa20676657f440f5c8f21583fcf7c5c2138d754e0262934417c92cfbb
+  signature: 7hALhs1hTjtnz3SdYmzKIqoniyvJDk5LyFcauv/wnVJRyZEQyPv42sb0Zk30zXAZ8QPE/g43/g4l78nv0AqNBQ==

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 import inspect
 import os
 import shutil
+import tempfile
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass
@@ -187,7 +188,10 @@ def _normalize_project_repo(repo: Path | None) -> Path | None:
     if repo is None:
         return None
     repo_path = repo.resolve()
+    temp_root = Path(tempfile.gettempdir()).resolve()
     for candidate in [repo_path, *repo_path.parents]:
+        if candidate == temp_root and candidate != repo_path:
+            return repo_path
         if (candidate / ".git").exists():
             return candidate
     return repo_path

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/src/specfact_cli/registry/module_availability.py

@@ -14,6 +14,7 @@ from specfact_cli.registry.module_discovery import DiscoveredModule, discover_al
 from specfact_cli.registry.module_packages import (
     _check_core_compatibility,
     _validate_module_dependencies,
+    get_module_load_failure_reason,
     merge_module_state,
 )
 from specfact_cli.registry.module_state import read_modules_state
@@ -104,6 +105,9 @@ def _recovery_command(status: ModuleAvailabilityStatus, module_id: str) -> str:
 
 def _skip_reason(entry: DiscoveredModule, enabled_map: dict[str, bool]) -> str:
     meta = entry.metadata
+    load_failure = get_module_load_failure_reason(meta.name, None)
+    if load_failure:
+        return load_failure
     if not _check_core_compatibility(meta, cli_version):
         return f"requires {meta.core_compatibility}, cli is {cli_version}"
     deps_ok, missing = _validate_module_dependencies(meta, enabled_map)
@@ -193,7 +197,13 @@ def classify_module_availability(
     command_name: str | None = None,
     base_path: Path | None = None,
 ) -> ModuleAvailability:
-    """Classify module availability using manifests and modules.json only."""
+    """
+    Classify module availability from discovery state and process load failures.
+
+    Decisions use manifests/modules.json plus the process-scoped lazy-load failure
+    registry exposed by get_module_load_failure_reason and backed by
+    _MODULE_LOAD_FAILURES.
+    """
     discovered = discover_all_modules_for_project_with_shadowed(base_path)
     matches = _availability_matches(discovered, module_id=module_id, command_name=command_name)
     requested_id = module_id or command_name or ""

{specfact_cli-0.46.17 → specfact_cli-0.46.19}/src/specfact_cli/registry/module_packages.py

@@ -13,7 +13,12 @@ import ast
 import importlib
 import importlib.util
 import os
+import re
+import site
 import sys
+import sysconfig
+import tempfile
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, cast
@@ -106,6 +111,8 @@ PROTOCOL_METHODS: dict[str, str] = {
 PROTOCOL_INTERFACE_BINDINGS: tuple[str, ...] = ("runtime_interface", "commands_interface", "commands")
 BRIDGE_REGISTRY = BridgeRegistry()
 BUILTIN_MODULES_ROOT = (Path(__file__).resolve().parents[1] / "modules").resolve()
+_ACTIVE_MODULE_SRC_DIRS: list[Path] = []
+_MODULE_LOAD_FAILURES: dict[tuple[str, str], str] = {}
 
 
 def _normalized_module_name(package_name: str) -> str:
@@ -141,6 +148,51 @@ def _is_builtin_module_package(package_dir: Path) -> bool:
         return False
 
 
+def _is_under_directory(path: Path, parent: Path) -> bool:
+    try:
+        path.resolve().relative_to(parent.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _installed_package_search_roots() -> tuple[Path, ...]:
+    """Return interpreter-managed roots that can contain installed packages."""
+    roots: list[Path] = []
+    for key in ("purelib", "platlib"):
+        raw_path = sysconfig.get_paths().get(key)
+        if raw_path:
+            roots.append(Path(raw_path))
+    with suppress(AttributeError):
+        roots.extend(Path(path) for path in site.getsitepackages())
+    return tuple(dict.fromkeys(root.resolve() for root in roots if root.exists()))
+
+
+def _has_installed_distribution_metadata(package_dir: Path) -> bool:
+    """Return True when package_dir has adjacent Python distribution metadata."""
+    parent = package_dir.parent
+    normalized = re.sub(r"[-_.]+", "_", package_dir.name).lower()
+    metadata_dirs = [*parent.glob("*.dist-info"), *parent.glob("*.egg-info")]
+    return any(re.sub(r"[-_.]+", "_", path.name).lower().startswith(f"{normalized}_") for path in metadata_dirs)
+
+
+def _is_managed_specfact_module_package(package_dir: Path) -> bool:
+    """Return True for modules installed under a SpecFact-managed modules root."""
+    parts = package_dir.resolve().parts
+    return ".specfact" in parts and "modules" in parts
+
+
+def _is_installed_module_package(package_dir: Path) -> bool:
+    """Return True when package_dir represents an installed package, not a source checkout."""
+    if _is_builtin_module_package(package_dir):
+        return False
+    if _is_managed_specfact_module_package(package_dir):
+        return True
+    if _has_installed_distribution_metadata(package_dir):
+        return True
+    return any(_is_under_directory(package_dir, root) for root in _installed_package_search_roots())
+
+
 @beartype
 @ensure(lambda result: isinstance(result, list), "Must return a list of paths")
 def get_modules_roots() -> list[Path]:
@@ -180,16 +232,16 @@ def get_modules_roots() -> list[Path]:
 def get_workspace_modules_root(base_path: Path | None = None) -> Path | None:
     """Return nearest workspace-local .specfact/modules root from base path upward."""
     start = base_path.resolve() if base_path is not None else Path.cwd().resolve()
+    temp_root = Path(tempfile.gettempdir()).resolve()
     for candidate in [start, *start.parents]:
+        if candidate == temp_root and candidate != start:
+            return None
+        workspace_modules_root = candidate / ".specfact" / "modules"
+        if workspace_modules_root.exists():
+            return workspace_modules_root
         git_dir = candidate / ".git"
         if git_dir.exists():
-            workspace_modules_root = candidate / ".specfact" / "modules"
-            if workspace_modules_root.exists():
-                return workspace_modules_root
             return None
-    workspace_modules_root = start / ".specfact" / "modules"
-    if workspace_modules_root.exists():
-        return workspace_modules_root
     return None
 
 
@@ -601,10 +653,77 @@ def _resolve_command_loader_path(
     return load_path, submodule_locations
 
 
+def _remember_active_module_src(package_dir: Path) -> None:
+    """Remember an eligible installed module source root for lazy cross-module imports."""
+    if not _is_installed_module_package(package_dir):
+        return
+    src_dir = package_dir / "src"
+    if not src_dir.is_dir():
+        return
+    resolved = src_dir.resolve()
+    if resolved not in _ACTIVE_MODULE_SRC_DIRS:
+        _ACTIVE_MODULE_SRC_DIRS.insert(0, resolved)
+
+
+def _prepend_active_module_src_roots() -> None:
+    """Prepend eligible installed module source roots before loading a command app."""
+    for src_dir in reversed(_ACTIVE_MODULE_SRC_DIRS):
+        src = str(src_dir)
+        if src not in sys.path:
+            sys.path.insert(0, src)
+
+
+def _record_module_load_failure(package_name: str, command_name: str, reason: str) -> None:
+    _MODULE_LOAD_FAILURES[(package_name, command_name)] = reason
+    _MODULE_LOAD_FAILURES[(package_name, "*")] = reason
+
+
+def _clear_module_load_failure(package_name: str, command_name: str) -> None:
+    _MODULE_LOAD_FAILURES.pop((package_name, command_name), None)
+    has_remaining_failure = any(
+        registered_package == package_name and registered_command != "*"
+        for registered_package, registered_command in _MODULE_LOAD_FAILURES
+    )
+    if not has_remaining_failure:
+        _MODULE_LOAD_FAILURES.pop((package_name, "*"), None)
+
+
+def _clear_active_module_src_dirs() -> None:
+    for src_dir in _ACTIVE_MODULE_SRC_DIRS:
+        src = str(src_dir)
+        while src in sys.path:
+            sys.path.remove(src)
+    _ACTIVE_MODULE_SRC_DIRS.clear()
+
+
+@beartype
+@ensure(lambda result: result is None, "must return None")
+def clear_module_load_failures() -> None:
+    """Clear process-scoped lazy module load failure diagnostics."""
+    _MODULE_LOAD_FAILURES.clear()
+
+
+def _package_name_non_empty(package_name: str) -> bool:
+    return bool(package_name.strip())
+
+
+@beartype
+@require(_package_name_non_empty, "package name must be non-empty")
+@ensure(lambda result: result is None or isinstance(result, str), "result must be a string or None")
+def get_module_load_failure_reason(package_name: str, command_name: str | None = None) -> str | None:
+    """Return the latest lazy-load failure for a module, if one was captured."""
+    if command_name is not None:
+        specific = _MODULE_LOAD_FAILURES.get((package_name, command_name))
+        if specific:
+            return specific
+    return _MODULE_LOAD_FAILURES.get((package_name, "*"))
+
+
 def _make_package_loader(package_dir: Path, package_name: str, command_name: str) -> Any:
     """Return a callable that loads the package's app (from src/app.py or src/<name>/__init__.py)."""
 
     def loader() -> Any:
+        _prepend_active_module_src_roots()
         src_dir = package_dir / "src"
         if str(src_dir) not in sys.path:
             sys.path.insert(0, str(src_dir))
@@ -621,18 +740,23 @@ def _make_package_loader(package_dir: Path, package_name: str, command_name: str
         sys.modules[spec.name] = mod
         try:
             spec.loader.exec_module(mod)
-        except (ImportError, ModuleNotFoundError, OSError) as exc:
-            raise ValueError(
+        except Exception as exc:
+            message = (
                 "Runtime compatibility error while loading "
                 f"module '{package_name}' command '{command_name}' from {package_dir}: {exc}. "
                 f"Reinstall the module and run SpecFact with the same Python interpreter ({sys.executable})."
-            ) from exc
+            )
+            _record_module_load_failure(package_name, command_name, message)
+            raise ValueError(message) from exc
         command_attr = f"{_normalized_module_name(command_name)}_app"
         app = getattr(mod, command_attr, None)
         if app is None:
             app = getattr(mod, "app", None)
         if app is None:
-            raise ValueError(f"Package {package_dir.name} has no '{command_attr}' or 'app' attribute")
+            message = f"Package {package_dir.name} has no '{command_attr}' or 'app' attribute"
+            _record_module_load_failure(package_name, command_name, message)
+            raise ValueError(message)
+        _clear_module_load_failure(package_name, command_name)
         return app
 
     return loader
@@ -1331,6 +1455,7 @@ def _register_one_package_if_eligible(package_dir: Path, meta: Any, reg: _Packag
     _register_schema_extensions_safe(meta, reg.logger)
     _register_service_bridges_safe(meta, reg.bridge_owner_map, reg.logger)
     _record_protocol_compliance_result(package_dir, meta, reg.logger, reg.counters)
+    _remember_active_module_src(package_dir)
     _register_commands_for_package(package_dir, meta, reg.category_grouping_enabled, reg.logger)
 
 
@@ -1382,6 +1507,8 @@ def register_module_package_commands(
     disable_ids = disable_ids or []
     if allow_unsigned is None:
         allow_unsigned = os.environ.get("SPECFACT_ALLOW_UNSIGNED", "").strip().lower() in ("1", "true", "yes")
+    _clear_active_module_src_dirs()
+    _MODULE_LOAD_FAILURES.clear()
     is_test_mode = os.environ.get("TEST_MODE") == "true" or os.environ.get("PYTEST_CURRENT_TEST") is not None
     packages = discover_all_package_metadata()
     packages = sorted(packages, key=_package_sort_key)