specfact-cli 0.26.9__tar.gz → 0.26.11__tar.gz

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/.gitignore

@@ -96,7 +96,10 @@ docs/internal/
 # Ignore .specify artifacts
 .specify/
 .cursor/commands/speckit.*
-specs/
+/specs/
+
+# Include openspec/specs/ directory
+!openspec/
 
 # Ignore specfact-cli prompt templates
 .cursor/commands/specfact-*

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.9
+Version: 0.26.11
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.9"
+version = "0.26.11"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"

specfact_cli-0.26.11/src/__init__.py

@@ -0,0 +1,6 @@
+"""
+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.26.11"

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/__init__.py

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

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/adapters/ado.py

@@ -2938,7 +2938,13 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             from specfact_cli.backlog.converter import convert_ado_work_item_to_backlog_item
 
             for work_item in work_items_data.get("value", []):
-                backlog_item = convert_ado_work_item_to_backlog_item(work_item, provider="ado")
+                backlog_item = convert_ado_work_item_to_backlog_item(
+                    work_item,
+                    provider="ado",
+                    base_url=self.base_url,
+                    org=self.org,
+                    project_name=self.project,
+                )
                 items.append(backlog_item)
 
         # Apply post-fetch filters that ADO API doesn't support directly
@@ -3258,4 +3264,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Convert back to BacklogItem
         from specfact_cli.backlog.converter import convert_ado_work_item_to_backlog_item
 
-        return convert_ado_work_item_to_backlog_item(updated_work_item, provider="ado")
+        return convert_ado_work_item_to_backlog_item(
+            updated_work_item,
+            provider="ado",
+            base_url=self.base_url,
+            org=self.org,
+            project_name=self.project,
+        )

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/adapters/openspec.py

@@ -57,11 +57,12 @@ class OpenSpecAdapter(BridgeAdapter):
         if bridge_config and bridge_config.external_base_path:
             base_path = bridge_config.external_base_path
 
-        # Check for OpenSpec structure
+        # Check for OpenSpec structure (OPSX: config.yaml; legacy: project.md; or specs dir)
+        config_yaml = base_path / "openspec" / "config.yaml"
         project_md = base_path / "openspec" / "project.md"
         specs_dir = base_path / "openspec" / "specs"
 
-        return project_md.exists() or (specs_dir.exists() and specs_dir.is_dir())
+        return config_yaml.exists() or project_md.exists() or (specs_dir.exists() and specs_dir.is_dir())
 
     @beartype
     @require(lambda repo_path: repo_path.exists(), "Repository path must exist")
@@ -179,8 +180,9 @@ class OpenSpecAdapter(BridgeAdapter):
         """
         config = BridgeConfig.preset_openspec()
 
-        # Check if OpenSpec is in external repo
-        if not (repo_path / "openspec" / "project.md").exists():
+        # Check if OpenSpec is in external repo (OPSX: config.yaml; legacy: project.md)
+        openspec_dir = repo_path / "openspec"
+        if not (openspec_dir / "config.yaml").exists() and not (openspec_dir / "project.md").exists():
             # Try to find external OpenSpec (this is a simple heuristic)
             # In practice, external_base_path should be provided via CLI option
             pass
@@ -422,10 +424,13 @@ class OpenSpecAdapter(BridgeAdapter):
         bridge_config: BridgeConfig | None,
         base_path: Path | None,
     ) -> None:
-        """Import project context from OpenSpec project.md."""
+        """Import project context from OpenSpec project.md (legacy) or config.yaml (OPSX)."""
         from specfact_cli.models.plan import Idea
 
-        parsed = self.parser.parse_project_md(project_md_path)
+        if project_md_path.name == "config.yaml" or project_md_path.suffix in (".yaml", ".yml"):
+            parsed = self.parser.parse_config_yaml(project_md_path)
+        else:
+            parsed = self.parser.parse_project_md(project_md_path)
 
         # Create Idea if it doesn't exist
         if not hasattr(project_bundle, "idea") or project_bundle.idea is None:

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/adapters/openspec_parser.py

@@ -2,7 +2,8 @@
 OpenSpec parser for adapter-specific OpenSpec format parsing.
 
 This module provides parsing functionality for OpenSpec artifacts:
-- project.md (project context)
+- project.md (project context, legacy)
+- config.yaml (OPSX project context)
 - spec.md (feature specifications)
 - proposal.md (change proposals)
 - spec.md with ADDED/MODIFIED/REMOVED markers (delta specs)
@@ -13,6 +14,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
+import yaml
 from beartype import beartype
 from icontract import ensure, require
 
@@ -55,6 +57,37 @@ class OpenSpecParser:
             # Return None on parse error (consistent with missing file)
             return None
 
+    @beartype
+    @require(lambda path: isinstance(path, Path), "Path must be Path")
+    @ensure(lambda result: result is None or isinstance(result, dict), "Must return dict or None")
+    def parse_config_yaml(self, path: Path) -> dict[str, Any] | None:
+        """
+        Parse OpenSpec OPSX config.yaml (project context).
+
+        Args:
+            path: Path to openspec/config.yaml file
+
+        Returns:
+            Dictionary compatible with project context import:
+            - "context": List of context string(s) from context: block
+            - "purpose": Optional (empty list if not in YAML)
+            - "raw_content": Full file content
+        """
+        if not path.exists():
+            return None
+
+        try:
+            content = path.read_text(encoding="utf-8")
+            data = yaml.safe_load(content) or {}
+            result: dict[str, Any] = {"purpose": [], "context": [], "raw_content": content}
+            if isinstance(data.get("context"), str):
+                result["context"] = [data["context"].strip()]
+            elif isinstance(data.get("context"), list):
+                result["context"] = [str(c).strip() for c in data["context"] if c]
+            return result
+        except Exception:
+            return None
+
     @beartype
     @require(lambda path: isinstance(path, Path), "Path must be Path")
     @ensure(lambda result: result is None or isinstance(result, dict), "Must return dict or None")

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/backlog/converter.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
+from urllib.parse import quote
 
 from beartype import beartype
 from icontract import ensure, require
@@ -157,7 +158,12 @@ def convert_github_issue_to_backlog_item(item_data: dict[str, Any], provider: st
 @require(lambda provider: isinstance(provider, str) and len(provider) > 0, "Provider must be non-empty string")
 @ensure(lambda result: isinstance(result, BacklogItem), "Must return BacklogItem")
 def convert_ado_work_item_to_backlog_item(
-    item_data: dict[str, Any], provider: str = "ado", custom_mapping_file: str | Path | None = None
+    item_data: dict[str, Any],
+    provider: str = "ado",
+    custom_mapping_file: str | Path | None = None,
+    base_url: str | None = None,
+    org: str | None = None,
+    project_name: str | None = None,
 ) -> BacklogItem:
     """
     Convert Azure DevOps work item data to BacklogItem.
@@ -167,6 +173,10 @@ def convert_ado_work_item_to_backlog_item(
     Args:
         item_data: ADO work item data from API (dict)
         provider: Provider name (default: "ado")
+        custom_mapping_file: Optional path to custom ADO field mapping file.
+        base_url: ADO base URL (e.g. https://dev.azure.com) for canonical URL.
+        org: ADO organization name for canonical URL.
+        project_name: ADO project name (URL-encoded in canonical URL) for opening in browser.
 
     Returns:
         BacklogItem instance with normalized fields
@@ -294,10 +304,17 @@ def convert_ado_work_item_to_backlog_item(
         "_links": item_data.get("_links", {}),
     }
 
+    canonical_url = None
+    if base_url and org and project_name:
+        base = base_url.rstrip("/")
+        encoded_project = quote(project_name, safe="")
+        canonical_url = f"{base}/{org}/{encoded_project}/_workitems/edit/{work_item_id}"
+
     return BacklogItem(
         id=work_item_id,
         provider=provider,
         url=url,
+        canonical_url=canonical_url,
         title=title,
         body_markdown=body_markdown,
         state=state,

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/commands/backlog_commands.py

@@ -14,6 +14,7 @@ SpecFact CLI Architecture:
 from __future__ import annotations
 
 import os
+import re
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -202,6 +203,97 @@ def _build_adapter_kwargs(
     return kwargs
 
 
+def _extract_body_from_block(block: str) -> str:
+    """
+    Extract **Body** content from a refined export block, handling nested fenced code.
+
+    The body is wrapped in ```markdown ... ```. If the body itself contains fenced
+    code blocks (e.g. ```python ... ```), the closing fence is matched by tracking
+    depth: a line that is exactly ``` closes the current fence (body or inner).
+    """
+    start_marker = "**Body**:"
+    fence_open = "```markdown"
+    if start_marker not in block or fence_open not in block:
+        return ""
+    idx = block.find(start_marker)
+    rest = block[idx + len(start_marker) :].lstrip()
+    if not rest.startswith("```"):
+        return ""
+    if not rest.startswith(fence_open + "\n") and not rest.startswith(fence_open + "\r\n"):
+        return ""
+    after_open = rest[len(fence_open) :].lstrip("\n\r")
+    if not after_open:
+        return ""
+    lines = after_open.split("\n")
+    body_lines: list[str] = []
+    depth = 1
+    for line in lines:
+        stripped = line.rstrip()
+        if stripped == "```":
+            if depth == 1:
+                break
+            depth -= 1
+            body_lines.append(line)
+        elif stripped.startswith("```") and stripped != "```":
+            depth += 1
+            body_lines.append(line)
+        else:
+            body_lines.append(line)
+    return "\n".join(body_lines).strip()
+
+
+def _parse_refined_export_markdown(content: str) -> dict[str, dict[str, Any]]:
+    """
+    Parse refined export markdown (same format as --export-to-tmp) into id -> fields.
+
+    Splits by ## Item blocks, extracts **ID**, **Body** (from ```markdown ... ```),
+    **Acceptance Criteria**, and optionally title and **Metrics** (story_points,
+    business_value, priority). Body extraction is fence-aware so bodies containing
+    nested code blocks are parsed correctly. Returns a dict mapping item id to
+    parsed fields (body_markdown, acceptance_criteria, title?, story_points?,
+    business_value?, priority?).
+    """
+    result: dict[str, dict[str, Any]] = {}
+    blocks = re.split(r"\n## Item \d+:", content)
+    for block in blocks:
+        block = block.strip()
+        if not block or block.startswith("# SpecFact") or "**ID**:" not in block:
+            continue
+        id_match = re.search(r"\*\*ID\*\*:\s*(.+?)(?:\n|$)", block)
+        if not id_match:
+            continue
+        item_id = id_match.group(1).strip()
+        fields: dict[str, Any] = {}
+
+        fields["body_markdown"] = _extract_body_from_block(block)
+
+        ac_match = re.search(r"\*\*Acceptance Criteria\*\*:\s*\n(.*?)(?=\n\*\*|\n---|\Z)", block, re.DOTALL)
+        if ac_match:
+            fields["acceptance_criteria"] = ac_match.group(1).strip() or None
+        else:
+            fields["acceptance_criteria"] = None
+
+        first_line = block.split("\n")[0].strip() if block else ""
+        if first_line and not first_line.startswith("**"):
+            fields["title"] = first_line
+
+        if "Story Points:" in block:
+            sp_match = re.search(r"Story Points:\s*(\d+)", block)
+            if sp_match:
+                fields["story_points"] = int(sp_match.group(1))
+        if "Business Value:" in block:
+            bv_match = re.search(r"Business Value:\s*(\d+)", block)
+            if bv_match:
+                fields["business_value"] = int(bv_match.group(1))
+        if "Priority:" in block:
+            pri_match = re.search(r"Priority:\s*(\d+)", block)
+            if pri_match:
+                fields["priority"] = int(pri_match.group(1))
+
+        result[item_id] = fields
+    return result
+
+
 def _fetch_backlog_items(
     adapter_name: str,
     search_query: str | None = None,
@@ -635,6 +727,8 @@ def refine(
                 export_content += f"## Item {idx}: {item.title}\n\n"
                 export_content += f"**ID**: {item.id}\n"
                 export_content += f"**URL**: {item.url}\n"
+                if item.canonical_url:
+                    export_content += f"**Canonical URL**: {item.canonical_url}\n"
                 export_content += f"**State**: {item.state}\n"
                 export_content += f"**Provider**: {item.provider}\n"
 
@@ -678,9 +772,65 @@ def refine(
                 raise typer.Exit(1)
 
             console.print(f"[bold cyan]Importing refined content from: {import_file}[/bold cyan]")
-            # TODO: Implement import logic to parse refined content and apply to items
-            console.print("[yellow]⚠ Import functionality pending implementation[/yellow]")
-            console.print("[dim]For now, use interactive refinement with --write flag[/dim]")
+            raw = import_file.read_text(encoding="utf-8")
+            parsed_by_id = _parse_refined_export_markdown(raw)
+            if not parsed_by_id:
+                console.print(
+                    "[yellow]No valid item blocks found in import file (expected ## Item N: and **ID**:)[/yellow]"
+                )
+                raise typer.Exit(1)
+
+            updated_items: list[BacklogItem] = []
+            for item in items:
+                if item.id not in parsed_by_id:
+                    continue
+                data = parsed_by_id[item.id]
+                item.body_markdown = data.get("body_markdown", item.body_markdown or "")
+                if "acceptance_criteria" in data:
+                    item.acceptance_criteria = data["acceptance_criteria"]
+                if data.get("title"):
+                    item.title = data["title"]
+                if "story_points" in data:
+                    item.story_points = data["story_points"]
+                if "business_value" in data:
+                    item.business_value = data["business_value"]
+                if "priority" in data:
+                    item.priority = data["priority"]
+                updated_items.append(item)
+
+            if not write:
+                console.print(f"[green]Would update {len(updated_items)} item(s)[/green]")
+                console.print("[dim]Run with --write to apply changes to the backlog[/dim]")
+                return
+
+            writeback_kwargs = _build_adapter_kwargs(
+                adapter,
+                repo_owner=repo_owner,
+                repo_name=repo_name,
+                github_token=github_token,
+                ado_org=ado_org,
+                ado_project=ado_project,
+                ado_team=ado_team,
+                ado_token=ado_token,
+            )
+            adapter_instance = adapter_registry.get_adapter(adapter, **writeback_kwargs)
+            if not isinstance(adapter_instance, BacklogAdapter):
+                console.print("[bold red]✗[/bold red] Adapter does not support backlog updates")
+                raise typer.Exit(1)
+
+            for item in updated_items:
+                update_fields_list = ["title", "body_markdown"]
+                if item.acceptance_criteria:
+                    update_fields_list.append("acceptance_criteria")
+                if item.story_points is not None:
+                    update_fields_list.append("story_points")
+                if item.business_value is not None:
+                    update_fields_list.append("business_value")
+                if item.priority is not None:
+                    update_fields_list.append("priority")
+                adapter_instance.update_backlog_item(item, update_fields=update_fields_list)
+                console.print(f"[green]✓ Updated backlog item: {item.url}[/green]")
+            console.print(f"[green]✓ Updated {len(updated_items)} backlog item(s)[/green]")
             return
 
         # Apply limit if specified
@@ -806,6 +956,8 @@ def refine(
                 console.print("\n[bold]Preview Mode: Full Item Details[/bold]")
                 console.print(f"[bold]Title:[/bold] {item.title}")
                 console.print(f"[bold]URL:[/bold] {item.url}")
+                if item.canonical_url:
+                    console.print(f"[bold]Canonical URL:[/bold] {item.canonical_url}")
                 console.print(f"[bold]State:[/bold] {item.state}")
                 console.print(f"[bold]Provider:[/bold] {item.provider}")
                 console.print(f"[bold]Assignee:[/bold] {', '.join(item.assignees) if item.assignees else 'Unassigned'}")
@@ -1227,7 +1379,7 @@ def map_fields(
     import re
     import sys
 
-    import questionary
+    import questionary  # type: ignore[reportMissingImports]
     import requests
 
     from specfact_cli.backlog.mappers.template_config import FieldMappingConfig

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/models/backlog_item.py

@@ -32,7 +32,11 @@ class BacklogItem(BaseModel):
     # Identity fields
     id: str = Field(..., description="Backlog item identifier (provider-specific)")
     provider: str = Field(..., description="Provider name (github, ado, jira, linear, etc.)")
-    url: str = Field(..., description="Backlog item URL")
+    url: str = Field(..., description="Backlog item URL (API or provider URL)")
+    canonical_url: str | None = Field(
+        default=None,
+        description="User-friendly URL for opening in browser (e.g. ADO: org/project-name/_workitems/edit/id)",
+    )
 
     # Content fields
     title: str = Field(..., description="Backlog item title")

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/models/bridge.py

@@ -499,7 +499,7 @@ class BridgeConfig(BaseModel):
         Returns:
             BridgeConfig for OpenSpec integration with artifact mappings for:
             - specification: openspec/specs/{feature_id}/spec.md
-            - project_context: openspec/project.md
+            - project_context: openspec/config.yaml (OPSX) if present, else openspec/project.md (legacy)
             - change_proposal: openspec/changes/{change_name}/proposal.md
             - change_tasks: openspec/changes/{change_name}/tasks.md
             - change_spec_delta: openspec/changes/{change_name}/specs/{feature_id}/spec.md

{specfact_cli-0.26.9 → specfact_cli-0.26.11}/src/specfact_cli/sync/bridge_sync.py

@@ -31,7 +31,7 @@ from rich.progress import Progress
 from rich.table import Table
 
 from specfact_cli.adapters.registry import AdapterRegistry
-from specfact_cli.models.bridge import BridgeConfig
+from specfact_cli.models.bridge import AdapterType, BridgeConfig
 from specfact_cli.runtime import get_configured_console
 from specfact_cli.sync.bridge_probe import BridgeProbe
 from specfact_cli.utils.bundle_loader import load_project_bundle, save_project_bundle
@@ -188,6 +188,19 @@ class BridgeSync:
             msg = "Bridge config not initialized"
             raise ValueError(msg)
 
+        base_path = self.repo_path
+        if self.bridge_config.external_base_path is not None:
+            base_path = self.bridge_config.external_base_path
+
+        if artifact_key == "project_context" and self.bridge_config.adapter == AdapterType.OPENSPEC:
+            config_yaml = base_path / "openspec" / "config.yaml"
+            project_md = base_path / "openspec" / "project.md"
+            if config_yaml.exists():
+                return config_yaml
+            if project_md.exists():
+                return project_md
+            return project_md
+
         context = {
             "feature_id": feature_id,
             "bundle_name": bundle_name,

specfact_cli-0.26.9/src/__init__.py

@@ -1,6 +0,0 @@
-"""
-SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
-"""
-
-# Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.26.7"