specfact-cli 0.40.0__tar.gz → 0.40.2__tar.gz

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.40.0
+Version: 0.40.2
 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
@@ -353,6 +353,8 @@ As of `0.40.0`, flat root commands are removed. Use grouped commands:
 ### Backlog Bridge (60 seconds)
 
 SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
+These commands require the backlog bundle to be installed first, for example via
+`specfact init --profile backlog-team` or `specfact init --install backlog`.
 
 ```bash
 # 1) Initialize backlog config + field mapping

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/README.md

@@ -74,6 +74,8 @@ As of `0.40.0`, flat root commands are removed. Use grouped commands:
 ### Backlog Bridge (60 seconds)
 
 SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
+These commands require the backlog bundle to be installed first, for example via
+`specfact init --profile backlog-team` or `specfact init --install backlog`.
 
 ```bash
 # 1) Initialize backlog config + field mapping

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.40.0"
+version = "0.40.2"
 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"
@@ -377,9 +377,10 @@ method = "thread"
 dev-mode-dirs = ["src","tools"]
 
 [tool.hatch.build.targets.wheel]
-packages = [
+only-include = [
     "src/specfact_cli",
 ]
+sources = ["src"]
 
 [tool.hatch.build.targets.wheel.force-include]
 "resources/prompts" = "specfact_cli/resources/prompts"
@@ -387,7 +388,6 @@ packages = [
 "resources/schemas" = "specfact_cli/resources/schemas"
 "resources/mappings" = "specfact_cli/resources/mappings"
 "resources/keys" = "specfact_cli/resources/keys"
-"modules/backlog-core" = "specfact_cli/modules/backlog-core"
 "modules/bundle-mapper" = "specfact_cli/modules/bundle-mapper"
 # Note: resources/semgrep files are in src/specfact_cli/resources/semgrep/ and are automatically included
 

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/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.40.0"
+__version__ = "0.40.2"

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/__init__.py

@@ -42,6 +42,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.40.0"
+__version__ = "0.40.2"
 
 __all__ = ["__version__"]

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/adapters/ado.py

@@ -3414,6 +3414,21 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 }
             )
 
+        provider_fields = payload.get("provider_fields")
+        provider_field_values = provider_fields.get("fields") if isinstance(provider_fields, dict) else None
+        if isinstance(provider_field_values, dict):
+            for field_name, field_value in provider_field_values.items():
+                normalized_field = str(field_name).strip()
+                if not normalized_field:
+                    continue
+                patch_document.append(
+                    {
+                        "op": "add",
+                        "path": f"/fields/{normalized_field}",
+                        "value": field_value,
+                    }
+                )
+
         sprint = str(payload.get("sprint") or "").strip()
         if sprint:
             patch_document.append(

specfact_cli-0.40.2/src/specfact_cli/backlog/__init__.py

@@ -0,0 +1,14 @@
+"""Shared backlog conversion helpers retained by core adapters."""
+
+from __future__ import annotations
+
+from specfact_cli.backlog.converter import (
+    convert_ado_work_item_to_backlog_item,
+    convert_github_issue_to_backlog_item,
+)
+
+
+__all__ = [
+    "convert_ado_work_item_to_backlog_item",
+    "convert_github_issue_to_backlog_item",
+]

specfact_cli-0.40.2/src/specfact_cli/backlog/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Backlog adapter contracts retained by core provider integrations."""
+
+from __future__ import annotations
+
+from specfact_cli.backlog.adapters.base import BacklogAdapter
+
+
+__all__ = ["BacklogAdapter"]

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/groups/__init__.py

@@ -1,8 +1,7 @@
-"""Category group commands: project, backlog, code, spec, govern."""
+"""Category group commands: project, code, spec, govern."""
 
 from __future__ import annotations
 
-from specfact_cli.groups.backlog_group import app as backlog_app
 from specfact_cli.groups.codebase_group import app as codebase_app
 from specfact_cli.groups.govern_group import app as govern_app
 from specfact_cli.groups.project_group import app as project_app
@@ -10,7 +9,6 @@ from specfact_cli.groups.spec_group import app as spec_app
 
 
 __all__ = [
-    "backlog_app",
     "codebase_app",
     "govern_app",
     "project_app",

specfact_cli-0.40.2/src/specfact_cli/groups/member_group.py

@@ -0,0 +1,60 @@
+"""Generic category group builder for bundle-owned command surfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import typer
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.registry.registry import CommandRegistry
+
+
+@require(lambda app: app is not None)
+@beartype
+def _register_members(app: typer.Typer, members: Sequence[tuple[str, str]]) -> int:
+    """Register member module sub-apps and return how many were added."""
+    added = 0
+    for display_name, cmd_name in members:
+        try:
+            member_app = CommandRegistry.get_module_typer(cmd_name)
+            if member_app is not None:
+                app.add_typer(member_app, name=display_name)
+                added += 1
+        except ValueError:
+            continue
+    return added
+
+
+@require(lambda name: isinstance(name, str) and len(name) > 0)
+@require(lambda help_text: isinstance(help_text, str) and len(help_text) > 0)
+@ensure(lambda result: isinstance(result, typer.Typer))
+@beartype
+def build_member_group(
+    *,
+    name: str,
+    help_text: str,
+    members: Sequence[tuple[str, str]],
+    flatten_same_name: str | None = None,
+    install_hint_module: str | None = None,
+) -> typer.Typer:
+    """Build a lazy category group from registered member modules."""
+    app = typer.Typer(name=name, help=help_text, no_args_is_help=True)
+    added = _register_members(app, members)
+
+    if added == 0 and install_hint_module:
+        placeholder = typer.Typer(help=f"{help_text} (module not loaded).")
+
+        @placeholder.command("install")
+        def _install_hint() -> None:
+            from specfact_cli.utils.prompts import print_warning
+
+            print_warning(f"No {name} module loaded. Install with: specfact module install {install_hint_module}")
+
+        app.add_typer(placeholder, name=name)
+
+    if flatten_same_name:
+        app._specfact_flatten_same_name = flatten_same_name
+
+    return app

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/registry/module_discovery.py

@@ -56,7 +56,14 @@ def discover_all_modules(
     effective_custom_root = custom_root or CUSTOM_MODULES_ROOT
 
     roots: list[tuple[str, Path]] = [("builtin", effective_builtin_root)]
+    project_matches_user_root = False
     if effective_project_root is not None:
+        try:
+            project_matches_user_root = effective_project_root.resolve() == effective_user_root.resolve()
+        except OSError:
+            project_matches_user_root = effective_project_root == effective_user_root
+
+    if effective_project_root is not None and not project_matches_user_root:
         roots.append(("project", effective_project_root))
     roots.extend(
         [

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/registry/module_packages.py

@@ -879,14 +879,24 @@ def get_installed_bundles(
 
 # Bundle name -> (group_name, help_str, build_app_fn) for conditional category mounting.
 def _build_bundle_to_group() -> dict[str, tuple[str, str, Any]]:
-    from specfact_cli.groups.backlog_group import build_app as build_backlog_app
     from specfact_cli.groups.codebase_group import build_app as build_codebase_app
     from specfact_cli.groups.govern_group import build_app as build_govern_app
+    from specfact_cli.groups.member_group import build_member_group
     from specfact_cli.groups.project_group import build_app as build_project_app
     from specfact_cli.groups.spec_group import build_app as build_spec_app
 
     return {
-        "specfact-backlog": ("backlog", "Backlog and policy commands.", build_backlog_app),
+        "specfact-backlog": (
+            "backlog",
+            "Backlog and policy commands.",
+            lambda: build_member_group(
+                name="backlog",
+                help_text="Backlog and policy commands.",
+                members=(("backlog", "backlog"), ("policy", "policy")),
+                flatten_same_name="backlog",
+                install_hint_module="nold-ai/specfact-backlog",
+            ),
+        ),
         "specfact-codebase": (
             "code",
             "Codebase quality commands: analyze, drift, validate, repro.",
@@ -1171,26 +1181,20 @@ def register_module_package_commands(
     if category_grouping_enabled:
         _mount_installed_category_groups(packages, enabled_map)
     discovered_count = protocol_full + protocol_partial + protocol_legacy
-    if discovered_count and (protocol_partial > 0 or protocol_legacy > 0):
-        print_warning(
-            "Module compatibility check: "
-            f"{protocol_full + protocol_partial}/{discovered_count} compliant "
-            f"(full={protocol_full}, partial={protocol_partial}, legacy={protocol_legacy})."
+    if discovered_count and (protocol_partial > 0 or protocol_legacy > 0) and is_debug_mode():
+        logger.info(
+            "Module compatibility check: %s/%s compliant (full=%s, partial=%s, legacy=%s)",
+            protocol_full + protocol_partial,
+            discovered_count,
+            protocol_full,
+            protocol_partial,
+            protocol_legacy,
         )
         if partial_modules:
             partial_desc = ", ".join(f"{name} ({'/'.join(ops)})" for name, ops in sorted(partial_modules))
-            print_warning(f"Partially compliant modules: {partial_desc}")
+            logger.info("Partially compliant modules: %s", partial_desc)
         if legacy_modules:
-            print_warning(f"Legacy modules: {', '.join(sorted(set(legacy_modules)))}")
-        if is_debug_mode():
-            logger.info(
-                "Protocol-compliant: %s/%s modules (Full=%s, Partial=%s, Legacy=%s)",
-                protocol_full + protocol_partial,
-                discovered_count,
-                protocol_full,
-                protocol_partial,
-                protocol_legacy,
-            )
+            logger.info("Legacy modules: %s", ", ".join(sorted(set(legacy_modules))))
     for module_id, reason in skipped:
         logger.debug("Skipped module '%s': %s", module_id, reason)
 

{specfact_cli-0.40.0 → specfact_cli-0.40.2}/src/specfact_cli/utils/ide_setup.py

@@ -121,10 +121,6 @@ SPECFACT_COMMANDS = [
     "specfact.06-sync",
     "specfact.07-contracts",
     "specfact.compare",
-    "specfact.sync-backlog",
-    "specfact.backlog-daily",
-    "specfact.backlog-refine",
-    "specfact.backlog-add",
     "specfact.validate",
 ]
 

specfact_cli-0.40.2/src/specfact_cli/validation/__init__.py

@@ -0,0 +1,14 @@
+"""Validation helpers for release and command-surface audits."""
+
+from specfact_cli.validation.command_audit import (
+    CommandAuditCase,
+    build_command_audit_cases,
+    official_marketplace_module_ids,
+)
+
+
+__all__ = [
+    "CommandAuditCase",
+    "build_command_audit_cases",
+    "official_marketplace_module_ids",
+]

specfact_cli-0.40.2/src/specfact_cli/validation/command_audit.py

@@ -0,0 +1,165 @@
+"""Helpers for command-package runtime validation."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+AuditMode = Literal["help-only", "fixture-backed", "dry-run"]
+
+
+@dataclass(frozen=True)
+class CommandAuditCase:
+    """One command-path audit case."""
+
+    command_path: str
+    argv: tuple[str, ...]
+    phase: str
+    mode: AuditMode
+    owner: str
+
+
+def _resolve_modules_repo_root() -> Path | None:
+    configured = os.environ.get("SPECFACT_MODULES_REPO", "").strip()
+    if configured:
+        candidate = Path(configured).expanduser().resolve()
+        if candidate.exists():
+            return candidate
+
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        sibling = parent.parent / "specfact-cli-modules"
+        if sibling.exists():
+            return sibling.resolve()
+        direct = parent / "specfact-cli-modules"
+        if direct.exists():
+            return direct.resolve()
+    return None
+
+
+def _ensure_bundle_sources_on_sys_path() -> None:
+    modules_repo = _resolve_modules_repo_root()
+    if modules_repo is None:
+        return
+    packages_root = modules_repo / "packages"
+    if not packages_root.exists():
+        return
+    for bundle_src in packages_root.glob("*/src"):
+        bundle_src_str = str(bundle_src.resolve())
+        if bundle_src_str not in sys.path:
+            sys.path.insert(0, bundle_src_str)
+
+
+def _command_info_name(command_info: object) -> str:
+    explicit_name = getattr(command_info, "name", None)
+    if isinstance(explicit_name, str) and explicit_name:
+        return explicit_name
+    callback = getattr(command_info, "callback", None)
+    callback_name = getattr(callback, "__name__", "")
+    return callback_name.replace("_", "-") if callback_name else ""
+
+
+def _collect_typer_paths(app: object, prefix: str) -> set[str]:
+    paths: set[str] = set()
+
+    for command_info in list(getattr(app, "registered_commands", [])):
+        command_name = _command_info_name(command_info)
+        if command_name:
+            paths.add(f"{prefix} {command_name}")
+
+    for group_info in list(getattr(app, "registered_groups", [])):
+        group_name = getattr(group_info, "name", "") or ""
+        if not group_name:
+            nested_app = getattr(group_info, "typer_instance", None)
+            nested_info = getattr(nested_app, "info", None) if nested_app is not None else None
+            group_name = getattr(nested_info, "name", "") or ""
+        if not group_name:
+            continue
+        group_prefix = f"{prefix} {group_name}"
+        paths.add(group_prefix)
+        nested_app = getattr(group_info, "typer_instance", None)
+        if nested_app is not None:
+            paths.update(_collect_typer_paths(nested_app, group_prefix))
+
+    return paths
+
+
+def _import_typer(module_path: str, attr_name: str = "app") -> object:
+    module = importlib.import_module(module_path)
+    return getattr(module, attr_name)
+
+
+def official_marketplace_module_ids() -> tuple[str, ...]:
+    """Return the official marketplace module ids that make up the full CLI surface."""
+    return (
+        "nold-ai/specfact-project",
+        "nold-ai/specfact-spec",
+        "nold-ai/specfact-codebase",
+        "nold-ai/specfact-backlog",
+        "nold-ai/specfact-govern",
+    )
+
+
+def _explicit_cases() -> list[CommandAuditCase]:
+    return [
+        CommandAuditCase("specfact", ("--help",), "root", "help-only", "specfact-core"),
+        CommandAuditCase("project", ("project", "--help"), "project", "help-only", "nold-ai/specfact-project"),
+        CommandAuditCase("spec", ("spec", "--help"), "spec", "help-only", "nold-ai/specfact-spec"),
+        CommandAuditCase("code", ("code", "--help"), "code", "help-only", "nold-ai/specfact-codebase"),
+        CommandAuditCase("backlog", ("backlog", "--help"), "backlog", "help-only", "nold-ai/specfact-backlog"),
+        CommandAuditCase("govern", ("govern", "--help"), "govern", "help-only", "nold-ai/specfact-govern"),
+        CommandAuditCase(
+            "module init", ("module", "init", "--scope", "user"), "core", "fixture-backed", "specfact-core"
+        ),
+        CommandAuditCase("module search", ("module", "search", "specfact"), "core", "fixture-backed", "specfact-core"),
+        CommandAuditCase("module list", ("module", "list", "--show-origin"), "core", "fixture-backed", "specfact-core"),
+        CommandAuditCase(
+            "module show",
+            ("module", "show", "nold-ai/specfact-backlog"),
+            "core",
+            "fixture-backed",
+            "specfact-core",
+        ),
+    ]
+
+
+def build_command_audit_cases() -> list[CommandAuditCase]:
+    """Build the full command audit matrix for core and official bundle command paths."""
+    _ensure_bundle_sources_on_sys_path()
+    app_specs = [
+        ("specfact_cli.modules.init.src.commands", "init", "core", "specfact-core", "import"),
+        ("specfact_cli.modules.module_registry.src.commands", "module", "core", "specfact-core", "import"),
+        ("specfact_cli.modules.upgrade.src.commands", "upgrade", "core", "specfact-core", "import"),
+        ("specfact_project.project.commands", "project", "project", "nold-ai/specfact-project", "import"),
+        ("specfact_spec.spec.commands", "spec", "spec", "nold-ai/specfact-spec", "import"),
+        ("specfact_codebase.code.commands", "code", "code", "nold-ai/specfact-codebase", "import"),
+        ("specfact_backlog.backlog.commands", "backlog", "backlog", "nold-ai/specfact-backlog", "import"),
+        ("specfact_govern.govern.commands", "govern", "govern", "nold-ai/specfact-govern", "import"),
+    ]
+
+    cases: dict[str, CommandAuditCase] = {case.command_path: case for case in _explicit_cases()}
+    for module_path, prefix, phase, owner, _load_mode in app_specs:
+        app = _import_typer(module_path)
+        cases.setdefault(
+            prefix,
+            CommandAuditCase(prefix, (*tuple(prefix.split()), "--help"), phase, "help-only", owner),
+        )
+        for command_path in sorted(_collect_typer_paths(app, prefix)):
+            cases.setdefault(
+                command_path,
+                CommandAuditCase(
+                    command_path,
+                    (*tuple(command_path.split()), "--help"),
+                    phase,
+                    "help-only",
+                    owner,
+                ),
+            )
+
+    phase_order = {"root": 0, "core": 1, "project": 2, "spec": 3, "code": 4, "backlog": 5, "govern": 6}
+    return sorted(cases.values(), key=lambda case: (phase_order.get(case.phase, 99), case.command_path))

specfact_cli-0.40.0/resources/prompts/specfact.backlog-add.md

@@ -1,90 +0,0 @@
----
-description: "Create backlog items with guided interactive flow and hierarchy checks"
----
-
-# SpecFact Backlog Add Command
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Purpose
-
-Create a new backlog item in GitHub or Azure DevOps using the `specfact backlog add` workflow. The command supports interactive prompts, parent hierarchy validation, DoR checks, and provider-specific fields.
-
-**When to use:** Adding new work items (epic/feature/story/task/bug) with consistent quality and parent-child structure.
-
-**Quick:** `/specfact.backlog-add --adapter github --project-id owner/repo --type story --title "..."`
-
-## Parameters
-
-### Required
-
-- `--adapter ADAPTER` - Backlog adapter (`github`, `ado`)
-- `--project-id PROJECT` - Project context
-  - GitHub: `owner/repo`
-  - ADO: `org/project`
-
-### Common options
-
-- `--type TYPE` - Backlog item type (provider/template specific)
-- `--title TITLE` - Item title
-- `--body BODY` - Item body/description
-- `--parent PARENT_ID` - Optional parent issue/work item id
-- `--non-interactive` - Disable prompt flow and require explicit inputs
-- `--check-dor` - Run Definition of Ready checks before create
-- `--template TEMPLATE` - Optional backlog template override
-- `--custom-config PATH` - Optional mapping/config override file
-
-### Adapter-specific options
-
-- GitHub:
-  - `--repo-owner OWNER`
-  - `--repo-name NAME`
-  - `--github-token TOKEN` (or `GITHUB_TOKEN`)
-- Azure DevOps:
-  - `--ado-org ORG`
-  - `--ado-project PROJECT`
-  - `--ado-token TOKEN` (or `AZURE_DEVOPS_TOKEN`)
-  - `--ado-base-url URL` (optional)
-
-## Workflow
-
-### Step 1: Execute command
-
-Run the CLI command with user arguments:
-
-```bash
-specfact backlog add [OPTIONS]
-```
-
-### Step 2: Interactive completion (if inputs are missing)
-
-- Prompt for missing required fields.
-- Prompt for optional quality fields (acceptance criteria, points, priority) when supported.
-- Validate parent selection and allowed hierarchy before create.
-
-### Step 3: Confirm and create
-
-- Show planned create payload summary.
-- Execute provider create operation.
-- Return created item id/key/url.
-
-## CLI Enforcement
-
-- Always execute `specfact backlog add` for creation.
-- Do not create provider issues/work items directly outside CLI unless user explicitly requests a manual path.
-
-## Input Contract
-
-- This command does not use `--export-to-tmp`/`--import-from-tmp` artifacts.
-- Provide values through CLI options or interactive prompts; do not fabricate external tmp-file schemas.
-- Do not ask Copilot to output `## Item N:` sections, `**ID**` labels, or markdown tmp files for this command.
-
-## Context
-
-{ARGS}