specfact-cli 0.46.4__tar.gz → 0.46.9__tar.gz

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.46.4"
+version = "0.46.9"
 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"
@@ -221,6 +221,7 @@ test-cov = "pytest --cov=src --cov-report=term-missing {args}"
 type-check = "basedpyright --pythonpath $(python -c 'import sys; print(sys.executable)') {args}"
 # basedpyright --level error: suppress warning noise in pre-commit (Block 1 runs `hatch run lint`).
 lint = "ruff format . --check && basedpyright --level error --pythonpath $(python -c 'import sys; print(sys.executable)') && ruff check . && pylint src tests tools && python scripts/verify_safe_project_writes.py"
+lint-changed = "python scripts/run_changed_lint.py {args}"
 governance = "pylint src tests tools --reports=y --output-format=parseable"
 format = "ruff check . --fix && ruff format ."
 

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/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.4"
+__version__ = "0.46.9"

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/__init__.py

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

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/analyzers/code_analyzer.py

@@ -32,6 +32,24 @@ from specfact_cli.utils.feature_keys import to_classname_key, to_sequential_key
 console = Console()
 
 
+def _ensure_semgrep_runtime_dir(repo_path: Path, relative: str) -> str:
+    """Create and return a stable repo-local runtime directory for Semgrep."""
+    path = (repo_path / relative).resolve()
+    path.mkdir(parents=True, exist_ok=True)
+    return str(path)
+
+
+def _build_semgrep_env(repo_path: Path) -> dict[str, str]:
+    """Build a repo-local Semgrep runtime env so CLI startup stays deterministic."""
+    env = dict(os.environ)
+    env["XDG_CONFIG_HOME"] = _ensure_semgrep_runtime_dir(repo_path, ".specfact/config")
+    env["XDG_CACHE_HOME"] = _ensure_semgrep_runtime_dir(repo_path, ".specfact/cache")
+    env["SEMGREP_VERSION_CACHE_PATH"] = _ensure_semgrep_runtime_dir(repo_path, ".specfact/cache/semgrep")
+    semgrep_log_dir = _ensure_semgrep_runtime_dir(repo_path, ".specfact/logs")
+    env["SEMGREP_LOG_FILE"] = str((Path(semgrep_log_dir) / "semgrep.log").resolve())
+    return env
+
+
 @dataclass
 class _SemgrepFeatureBuckets:
     api_endpoints: list[str] = field(default_factory=list)
@@ -457,6 +475,7 @@ class CodeAnalyzer:
                 capture_output=True,
                 text=True,
                 timeout=5,  # Increased timeout to 5s (Semgrep may need time to initialize)
+                env=_build_semgrep_env(self.repo_path),
             )
             return result.returncode == 0
         except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
@@ -566,6 +585,7 @@ class CodeAnalyzer:
                 capture_output=True,
                 text=True,
                 timeout=timeout,
+                env=_build_semgrep_env(self.repo_path),
             )
 
             # Semgrep may return non-zero for valid findings

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/cli.py

@@ -66,6 +66,7 @@ from specfact_cli.registry import CommandRegistry
 from specfact_cli.registry.alias_manager import resolve_command
 from specfact_cli.registry.bootstrap import register_builtin_commands
 from specfact_cli.registry.metadata import CommandMetadata
+from specfact_cli.registry.module_availability import ModuleAvailabilityStatus, classify_module_availability
 from specfact_cli.runtime import get_configured_console, init_debug_log_file, set_debug_mode
 from specfact_cli.utils.progressive_disclosure import ProgressiveDisclosureGroup
 from specfact_cli.utils.structured_io import StructuredFormat
@@ -124,6 +125,28 @@ def _print_missing_bundle_command_help(invoked: str) -> None:
     module_id = _INVOKED_TO_MARKETPLACE_MODULE.get(invoked)
     console = get_configured_console()
     if module_id is not None:
+        availability = classify_module_availability(module_id=module_id, command_name=invoked)
+        if availability.status is ModuleAvailabilityStatus.DISABLED:
+            console.print(
+                f"[bold red]Module '{availability.module_id or module_id}' is installed but disabled.[/bold red]\n"
+                f"The [bold]{invoked}[/bold] command group is provided by that module. "
+                f"Enable with [bold]{availability.recovery_command}[/bold]."
+            )
+            return
+        if availability.status is ModuleAvailabilityStatus.SKIPPED:
+            console.print(
+                f"[bold red]Module '{availability.module_id or module_id}' is installed but skipped.[/bold red]\n"
+                f"Reason: {availability.reason}. "
+                "Inspect with [bold]specfact module list --show-origin[/bold]."
+            )
+            return
+        if availability.status is ModuleAvailabilityStatus.SHADOWED:
+            console.print(
+                f"[bold red]Module '{availability.module_id or module_id}' is shadowed in this workspace.[/bold red]\n"
+                f"Shadowed by: {availability.shadowed_by}. "
+                "Inspect with [bold]specfact module list --show-origin[/bold]."
+            )
+            return
         console.print(
             f"[bold red]Module '{module_id}' is not installed.[/bold red]\n"
             f"The [bold]{invoked}[/bold] command group is provided by that module. "

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/modules/init/module-package.yaml

@@ -1,5 +1,5 @@
 name: init
-version: 0.1.30
+version: 0.1.31
 commands:
   - init
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: Initialize SpecFact workspace and bootstrap local configuration.
 license: Apache-2.0
 integrity:
-  checksum: sha256:9e03421972d3254082307834b474e7673957de8c11ffacc563f2da3f35e7cf05
-  signature: ikUYhUJ8AFU9RkB+ZBnp0lKrDLT7ZIqkauRYUMRY/swrIjRCTRzHIpNcvCmujK6h1w6EtT/+wGG1v5bZtZB8CQ==
+  checksum: sha256:0f7bc54a823bea14033fcb143ecb6c83d2bca2b5da661f03a0b545100acebe5b
+  signature: dTatkqgBUtti4tL/pmcFBZY9bsJ61gY/V0lP9gZU8Y5W3YWK+wpgRx1oewlAmfKzkxca2NhalKcjLACQjTNvAA==

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/modules/init/src/commands.py

@@ -106,7 +106,7 @@ def _resolve_field_mapping_templates_dir(repo_path: Path) -> Path | None:
         package_templates_dir = Path(str(templates_ref)).resolve()
         if package_templates_dir.exists():
             return package_templates_dir
-    except Exception:
+    except (ImportError, OSError, ValueError):
         try:
             import importlib.util
 
@@ -118,8 +118,8 @@ def _resolve_field_mapping_templates_dir(repo_path: Path) -> Path | None:
                 ).resolve()
                 if package_templates_dir.exists():
                     return package_templates_dir
-        except Exception:
-            pass
+        except (ImportError, OSError, ValueError):
+            return None
     return None
 
 
@@ -434,7 +434,15 @@ def _is_valid_repo_path(repo: Path) -> bool:
 
 
 @beartype
-def _install_profile_bundles(profile: str, install_root: Path, non_interactive: bool) -> None:
+def _marketplace_ids_for_bundles(bundle_ids: list[str]) -> list[str]:
+    return [
+        first_run_selection.MARKETPLACE_ONLY_BUNDLES[bid]
+        for bid in bundle_ids
+        if bid in first_run_selection.MARKETPLACE_ONLY_BUNDLES
+    ]
+
+
+def _install_profile_bundles(profile: str, install_root: Path, non_interactive: bool) -> list[str]:
     """Resolve profile to bundle list and install via module installer."""
     bundle_ids = first_run_selection.resolve_profile_bundles(profile)
     if bundle_ids:
@@ -444,10 +452,11 @@ def _install_profile_bundles(profile: str, install_root: Path, non_interactive:
             install_root,
             non_interactive=non_interactive,
         )
+    return _marketplace_ids_for_bundles(bundle_ids)
 
 
 @beartype
-def _install_bundle_list(install_arg: str, install_root: Path, non_interactive: bool) -> None:
+def _install_bundle_list(install_arg: str, install_root: Path, non_interactive: bool) -> list[str]:
     """Parse comma-separated or 'all' and install bundles via module installer."""
     bundle_ids = first_run_selection.resolve_install_bundles(install_arg)
     if bundle_ids:
@@ -457,20 +466,32 @@ def _install_bundle_list(install_arg: str, install_root: Path, non_interactive:
             install_root,
             non_interactive=non_interactive,
         )
+    return _marketplace_ids_for_bundles(bundle_ids)
 
 
-def _apply_profile_or_install_bundles(profile: str | None, install: str | None) -> None:
+def _apply_profile_or_install_bundles(profile: str | None, install: str | None) -> list[str]:
     try:
         non_interactive = is_non_interactive()
         if profile is not None:
-            _install_profile_bundles(profile, INIT_USER_MODULES_ROOT, non_interactive=non_interactive)
-        else:
-            _install_bundle_list(install or "", INIT_USER_MODULES_ROOT, non_interactive=non_interactive)
+            return _install_profile_bundles(profile, INIT_USER_MODULES_ROOT, non_interactive=non_interactive)
+        return _install_bundle_list(install or "", INIT_USER_MODULES_ROOT, non_interactive=non_interactive)
     except ValueError as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1) from e
 
 
+def _refresh_init_module_state(repo_path: Path, enabled_module_ids: list[str]) -> list[dict[str, Any]]:
+    modules_list = get_discovered_modules_for_state(
+        enable_ids=enabled_module_ids,
+        disable_ids=[],
+        base_path=repo_path,
+        preserve_existing=True,
+    )
+    if modules_list:
+        write_modules_state(modules_list)
+    return modules_list
+
+
 def _run_interactive_first_run_install() -> None:
     try:
         bundle_ids = _interactive_first_run_bundle_selection()
@@ -702,8 +723,9 @@ def init(
 
         repo_path = repo.resolve()
 
+        enabled_module_ids: list[str] = []
         if profile is not None or install is not None:
-            _apply_profile_or_install_bundles(profile, install)
+            enabled_module_ids = _apply_profile_or_install_bundles(profile, install)
         elif is_first_run(user_root=INIT_USER_MODULES_ROOT) and is_non_interactive():
             console.print(
                 "[red]Error:[/red] In CI/CD (non-interactive) mode, first-run init requires "
@@ -718,9 +740,7 @@ def init(
             _run_interactive_first_run_install()
 
         _init_user_visible_step("[cyan]→[/cyan] Discovering installed modules and writing registry state…")
-        modules_list = get_discovered_modules_for_state(enable_ids=[], disable_ids=[])
-        if modules_list:
-            write_modules_state(modules_list)
+        modules_list = _refresh_init_module_state(repo_path, enabled_module_ids)
 
         _init_user_visible_step("[cyan]→[/cyan] Indexing CLI commands for help cache…")
         run_discovery_and_write_cache(__version__)

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/modules/module_registry/module-package.yaml

@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.20
+version: 0.1.23
 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:a92afa757a54ee63b84ae4a5f5b232cb5dbddacfcb31fcde3abcdb4927eada8c
-  signature: jelDGPZyCLLpyzqH4+S2t7V9ICy/puYEzdUu/GX0oPiWgMZRg8aZlnECZGy+m+sHvS0XX3hPAXCSp3IJf6hHDg==
+  checksum: sha256:f500281d2249d712be23a1b25b5660374694dfa47634f60ae4378eb2cdb753ca
+  signature: cunuat95bD44IcNUBs35NTlHYOR8atydVz4ZyZTjIzwJL6Wz5YOfBYGq/WtgDnOFv3KplfvhRZbTo3CwmS/KBQ==

{specfact_cli-0.46.4 → specfact_cli-0.46.9}/src/specfact_cli/modules/module_registry/src/commands.py

@@ -20,12 +20,14 @@ from packaging.version import InvalidVersion, Version
 from rich.console import Console
 from rich.table import Table
 
+from specfact_cli import __version__
 from specfact_cli.models.module_package import ModulePackageMetadata
 from specfact_cli.modules import module_io_shim
 from specfact_cli.registry.alias_manager import create_alias, list_aliases, remove_alias
 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
+from specfact_cli.registry.module_discovery import discover_all_modules, discover_all_modules_for_project
 from specfact_cli.registry.module_installer import (
     REGISTRY_ID_FILE,
     USER_MODULES_ROOT,
@@ -42,7 +44,9 @@ from specfact_cli.registry.module_lifecycle import (
     render_modules_table,
     select_module_ids_interactive,
 )
+from specfact_cli.registry.module_packages import get_discovered_modules_for_state
 from specfact_cli.registry.module_security import ensure_publisher_trusted, is_official_publisher
+from specfact_cli.registry.module_state import read_modules_state, write_modules_state
 from specfact_cli.registry.registry import CommandRegistry
 from specfact_cli.runtime import is_non_interactive
 
@@ -178,15 +182,64 @@ def _resolve_install_target_root(scope_normalized: str, repo: Path | None) -> Pa
     return USER_MODULES_ROOT if scope_normalized == "user" else repo_path / ".specfact" / "modules"
 
 
+def _normalize_project_repo(repo: Path | None) -> Path | None:
+    """Resolve a project-scoped repo argument to the nearest workspace root."""
+    if repo is None:
+        return None
+    repo_path = repo.resolve()
+    for candidate in [repo_path, *repo_path.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+    return repo_path
+
+
+def _read_installed_manifest_id(module_dir: Path, fallback_name: str) -> str:
+    manifest_path = module_dir / "module-package.yaml"
+    try:
+        raw = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return fallback_name
+    if isinstance(raw, dict):
+        manifest = cast(dict[str, Any], raw)
+        if manifest.get("name"):
+            return str(manifest["name"])
+    return fallback_name
+
+
+def _enable_if_disabled(module_id: str, base_path: Path | None = None) -> bool:
+    state = read_modules_state()
+    if state.get(module_id, {}).get("enabled", True) is not False:
+        return False
+    modules = get_discovered_modules_for_state(
+        enable_ids=[module_id],
+        disable_ids=[],
+        base_path=base_path,
+        preserve_existing=True,
+    )
+    write_modules_state(modules)
+    run_discovery_and_write_cache(__version__)
+    return any(str(row.get("id", "")) == module_id and bool(row.get("enabled", True)) for row in modules)
+
+
 def _install_skip_if_already_satisfied(
     scope_normalized: str,
     requested_name: str,
     target_root: Path,
+    repo: Path | None,
     reinstall: bool,
     discovered_by_name: dict[str, Any],
 ) -> bool:
-    if (target_root / requested_name / "module-package.yaml").exists() and not reinstall:
-        console.print(f"[yellow]Module '{requested_name}' is already installed in {target_root}.[/yellow]")
+    installed_dir = target_root / requested_name
+    if (installed_dir / "module-package.yaml").exists() and not reinstall:
+        module_id = _read_installed_manifest_id(installed_dir, requested_name)
+        enabled = _enable_if_disabled(module_id, base_path=repo if scope_normalized == "project" else None)
+        if enabled:
+            console.print(
+                f"[yellow]Module '{module_id}' is already installed in {target_root}; "
+                "enabled it in module state.[/yellow]"
+            )
+        else:
+            console.print(f"[yellow]Module '{module_id}' is already installed in {target_root}.[/yellow]")
         return True
     skip_sources = {"builtin", "project", "user", "custom"}
     if scope_normalized == "project":
@@ -195,9 +248,14 @@ def _install_skip_if_already_satisfied(
         skip_sources.discard("project")
     existing = discovered_by_name.get(requested_name)
     if existing is not None and existing.source in skip_sources:
+        enabled = _enable_if_disabled(
+            existing.metadata.name,
+            base_path=repo if scope_normalized == "project" else None,
+        )
+        state_hint = " Enabled it in module state." if enabled else ""
         console.print(
-            f"[yellow]Module '{requested_name}' is already available from source '{existing.source}'. "
-            "No marketplace install needed.[/yellow]"
+            f"[yellow]Module '{existing.metadata.name}' is already available from source '{existing.source}'. "
+            f"No marketplace install needed.{state_hint}[/yellow]"
         )
         return True
     return False
@@ -274,6 +332,7 @@ class _InstallOneParams:
     scope_normalized: str
     source_normalized: str
     target_root: Path
+    repo: Path | None
     version: str | None
     reinstall: bool
     trust_non_official: bool
@@ -289,6 +348,7 @@ def _install_one(module_id: str, params: _InstallOneParams) -> bool:
         params.scope_normalized,
         requested_name,
         params.target_root,
+        params.repo,
         params.reinstall,
         params.discovered_by_name,
     ):
@@ -392,12 +452,17 @@ def _install_impl(module_ids: list[str], **kwargs: Any) -> None:
         )
         raise typer.Exit(1)
     scope_normalized, source_normalized = _parse_install_scope_and_source(scope, source)
-    target_root = _resolve_install_target_root(scope_normalized, repo)
-    discovered_by_name = {entry.metadata.name: entry for entry in discover_all_modules()}
+    normalized_repo = _normalize_project_repo(repo) if scope_normalized == "project" else None
+    target_root = _resolve_install_target_root(scope_normalized, normalized_repo)
+    discovered = (
+        discover_all_modules_for_project(normalized_repo) if normalized_repo is not None else discover_all_modules()
+    )
+    discovered_by_name = {entry.metadata.name: entry for entry in discovered}
     params = _InstallOneParams(
         scope_normalized=scope_normalized,
         source_normalized=source_normalized,
         target_root=target_root,
+        repo=normalized_repo,
         version=version,
         reinstall=reinstall,
         trust_non_official=trust_non_official,

specfact_cli-0.46.9/src/specfact_cli/registry/module_availability.py

@@ -0,0 +1,214 @@
+"""Metadata-only module availability classification for user-facing diagnostics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli import __version__ as cli_version
+from specfact_cli.registry.module_discovery import DiscoveredModule, discover_all_modules_for_project_with_shadowed
+from specfact_cli.registry.module_packages import (
+    _check_core_compatibility,
+    _validate_module_dependencies,
+    merge_module_state,
+)
+from specfact_cli.registry.module_state import read_modules_state
+
+
+class ModuleAvailabilityStatus(StrEnum):
+    """User-facing module availability states."""
+
+    ABSENT = "absent"
+    AVAILABLE = "available"
+    DISABLED = "disabled"
+    SKIPPED = "skipped"
+    SHADOWED = "shadowed"
+    AMBIGUOUS = "ambiguous"
+
+
+@dataclass(frozen=True)
+class ModuleAvailability:
+    """Availability classification without importing module command code."""
+
+    status: ModuleAvailabilityStatus
+    module_id: str | None = None
+    source: str | None = None
+    package_dir: Path | None = None
+    reason: str = ""
+    recovery_command: str = ""
+    shadowed_by: Path | None = None
+
+
+def _module_id_tail(module_id: str) -> str:
+    """Return the final path segment of a module id."""
+    return module_id.rsplit("/", 1)[-1].strip()
+
+
+def _module_id_matches(requested: str | None, discovered_id: str) -> bool:
+    """Return True when a requested module id refers to a discovered manifest id."""
+    if requested is None:
+        return False
+    requested_clean = requested.strip()
+    if "/" in requested_clean:
+        return requested_clean == discovered_id
+    return requested_clean == discovered_id or _module_id_tail(requested_clean) == _module_id_tail(discovered_id)
+
+
+def _entry_matches(entry: DiscoveredModule, *, module_id: str | None, command_name: str | None) -> bool:
+    meta = entry.metadata
+    if _module_id_matches(module_id, meta.name):
+        return True
+    if command_name is None:
+        return False
+    return command_name in set(meta.commands) or getattr(meta, "bundle_group_command", None) == command_name
+
+
+def _availability_matches(
+    discovered: list[DiscoveredModule],
+    *,
+    module_id: str | None,
+    command_name: str | None,
+) -> list[DiscoveredModule]:
+    module_matches = [entry for entry in discovered if _module_id_matches(module_id, entry.metadata.name)]
+    if module_matches:
+        return module_matches
+    if module_id is not None and "/" in module_id.strip():
+        return []
+    return [entry for entry in discovered if _entry_matches(entry, module_id=module_id, command_name=command_name)]
+
+
+def _ambiguous_bare_module_id_match(
+    module_id: str | None,
+    matches: list[DiscoveredModule],
+) -> bool:
+    if module_id is None:
+        return False
+    requested = module_id.strip()
+    if not requested or "/" in requested:
+        return False
+    matched_ids = {entry.metadata.name for entry in matches}
+    return len(matched_ids) > 1
+
+
+def _recovery_command(status: ModuleAvailabilityStatus, module_id: str) -> str:
+    if status is ModuleAvailabilityStatus.DISABLED:
+        return f"specfact module enable {module_id}"
+    if status is ModuleAvailabilityStatus.ABSENT:
+        return f"specfact module install {module_id}"
+    return ""
+
+
+def _skip_reason(entry: DiscoveredModule, enabled_map: dict[str, bool]) -> str:
+    meta = entry.metadata
+    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)
+    if not deps_ok:
+        return f"missing dependencies: {', '.join(missing)}"
+    return ""
+
+
+def _absent_availability(module_id: str | None, requested_id: str) -> ModuleAvailability:
+    return ModuleAvailability(
+        status=ModuleAvailabilityStatus.ABSENT,
+        module_id=module_id,
+        reason="not installed",
+        recovery_command=_recovery_command(ModuleAvailabilityStatus.ABSENT, requested_id) if requested_id else "",
+    )
+
+
+def _ambiguous_availability(module_id: str) -> ModuleAvailability:
+    return ModuleAvailability(
+        status=ModuleAvailabilityStatus.AMBIGUOUS,
+        module_id=module_id,
+        reason="multiple installed modules share this short id; use namespace/name",
+    )
+
+
+def _shadowed_duplicate(primary: DiscoveredModule, matches: list[DiscoveredModule]) -> DiscoveredModule | None:
+    duplicate = next((entry for entry in matches[1:] if entry.metadata.name == primary.metadata.name), None)
+    if duplicate is None:
+        return None
+    if primary.source == "project" and duplicate.source in {"user", "marketplace"}:
+        return duplicate
+    return None
+
+
+def _shadowed_availability(primary: DiscoveredModule, duplicate: DiscoveredModule) -> ModuleAvailability:
+    return ModuleAvailability(
+        status=ModuleAvailabilityStatus.SHADOWED,
+        module_id=duplicate.metadata.name,
+        source=duplicate.source,
+        package_dir=duplicate.package_dir,
+        reason=f"shadowed by {primary.source} scope",
+        shadowed_by=primary.package_dir,
+    )
+
+
+def _disabled_availability(primary: DiscoveredModule) -> ModuleAvailability:
+    module_name = primary.metadata.name
+    return ModuleAvailability(
+        status=ModuleAvailabilityStatus.DISABLED,
+        module_id=module_name,
+        source=primary.source,
+        package_dir=primary.package_dir,
+        reason="disabled in modules.json",
+        recovery_command=_recovery_command(ModuleAvailabilityStatus.DISABLED, module_name),
+    )
+
+
+def _available_or_skipped_availability(
+    primary: DiscoveredModule,
+    enabled_map: dict[str, bool],
+) -> ModuleAvailability:
+    reason = _skip_reason(primary, enabled_map)
+    if reason:
+        return ModuleAvailability(
+            status=ModuleAvailabilityStatus.SKIPPED,
+            module_id=primary.metadata.name,
+            source=primary.source,
+            package_dir=primary.package_dir,
+            reason=reason,
+        )
+    return ModuleAvailability(
+        status=ModuleAvailabilityStatus.AVAILABLE,
+        module_id=primary.metadata.name,
+        source=primary.source,
+        package_dir=primary.package_dir,
+    )
+
+
+@beartype
+@require(
+    lambda module_id, command_name, base_path: bool(module_id or command_name), "module_id or command_name required"
+)
+@ensure(lambda result: isinstance(result, ModuleAvailability), "must return module availability")
+def classify_module_availability(
+    *,
+    module_id: str | None = None,
+    command_name: str | None = None,
+    base_path: Path | None = None,
+) -> ModuleAvailability:
+    """Classify module availability using manifests and modules.json only."""
+    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 ""
+    if not matches:
+        return _absent_availability(module_id, requested_id)
+    if _ambiguous_bare_module_id_match(module_id, matches):
+        return _ambiguous_availability(requested_id.strip())
+
+    discovered_list = [(entry.metadata.name, entry.metadata.version) for entry in discovered]
+    enabled_map = merge_module_state(discovered_list, read_modules_state(), [], [])
+    primary = matches[0]
+    module_name = primary.metadata.name
+    duplicate = _shadowed_duplicate(primary, matches)
+    if duplicate is not None:
+        return _shadowed_availability(primary, duplicate)
+    if not enabled_map.get(module_name, True):
+        return _disabled_availability(primary)
+    return _available_or_skipped_availability(primary, enabled_map)