libspec 10.2.0__tar.gz → 10.3.3__tar.gz

{libspec-10.2.0 → libspec-10.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libspec
-Version: 10.2.0
+Version: 10.3.3
 Summary: Spec-driven development library for LLM-assisted coding
 Author-email: "Derek A. Rhodes" <physci@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -20,7 +20,6 @@ License-File: LICENSE
 Requires-Dist: click>=8.1.8
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: mcp>=1.27.0
-Requires-Dist: python-lsp-server>=1.12.2
 Requires-Dist: toml>=0.10.2
 Requires-Dist: skillkit>=0.4.0
 Requires-Dist: prompt-toolkit>=3.0.52
@@ -33,8 +32,6 @@ Dynamic: license-file
 
 [![CI/CD](https://github.com/drhodes/libspec/actions/workflows/ci.yml/badge.svg)](https://github.com/drhodes/libspec/actions/workflows/ci.yml)
 [![Documentation](https://github.com/drhodes/libspec/actions/workflows/docs.yml/badge.svg)](https://drhodes.github.io/libspec/)
-[![PyPI version](https://img.shields.io/pypi/v/libspec.svg)](https://pypi.org/project/libspec/)
-[![Python versions](https://img.shields.io/pypi/pyversions/libspec.svg)](https://pypi.org/project/libspec/)
 [![License](https://img.shields.io/github/license/drhodes/libspec.svg)](https://github.com/drhodes/libspec/blob/main/LICENSE)
 
 > **an ounce of spec is worth a pound of tokens**
@@ -169,10 +166,10 @@ Jinja2 template string. More about that later...
 ## Inheritance
 
 Inheritance means "does this and more." The inherited superclass
-docstrings are normative, but the compiled XML preserves them as
-`<inherits><ref>...</ref></inherits>` references instead of prepending
-their prose into the child docstring. Renderers such as `libspec diff`
-can expand those refs when a review needs the inherited context.
+docstrings are normative, but compiled spec snapshots preserve them as
+references instead of prepending their prose into the child docstring.
+Renderers such as `libspec diff` can expand those refs when a review
+needs the inherited context.
 
 ## Mixins 
 
@@ -181,6 +178,18 @@ Mixins help get around the diamond problem. (TODO: write more about this)
 ## Versioning
 
 Note that the versioning of `libspec` is still being hammered
-out. Currently, the version of `libspec` appears in the generated XML
+out. Currently, the version of `libspec` appears in generated spec snapshots
 (`libspec-version` field). But, how diffs will be performed on
 different versions is unexplored.
+
+## Feature Branch & Multi-Commit Spec Diffing
+
+When working on feature branches with intermediate commits, running `uv run libspec diff` right after a commit will report `No changes detected` because `HEAD` matches the live spec on disk.
+
+To track the cumulative specification delta across all intermediate commits on a feature branch, pass the base branch target:
+
+```bash
+uv run libspec diff main
+```
+
+This tracks all specification additions, requirement modifications, and docstring changes relative to `main` throughout multi-stage development workflows.

{libspec-10.2.0 → libspec-10.3.3}/README.md

@@ -2,8 +2,6 @@
 
 [![CI/CD](https://github.com/drhodes/libspec/actions/workflows/ci.yml/badge.svg)](https://github.com/drhodes/libspec/actions/workflows/ci.yml)
 [![Documentation](https://github.com/drhodes/libspec/actions/workflows/docs.yml/badge.svg)](https://drhodes.github.io/libspec/)
-[![PyPI version](https://img.shields.io/pypi/v/libspec.svg)](https://pypi.org/project/libspec/)
-[![Python versions](https://img.shields.io/pypi/pyversions/libspec.svg)](https://pypi.org/project/libspec/)
 [![License](https://img.shields.io/github/license/drhodes/libspec.svg)](https://github.com/drhodes/libspec/blob/main/LICENSE)
 
 > **an ounce of spec is worth a pound of tokens**
@@ -138,10 +136,10 @@ Jinja2 template string. More about that later...
 ## Inheritance
 
 Inheritance means "does this and more." The inherited superclass
-docstrings are normative, but the compiled XML preserves them as
-`<inherits><ref>...</ref></inherits>` references instead of prepending
-their prose into the child docstring. Renderers such as `libspec diff`
-can expand those refs when a review needs the inherited context.
+docstrings are normative, but compiled spec snapshots preserve them as
+references instead of prepending their prose into the child docstring.
+Renderers such as `libspec diff` can expand those refs when a review
+needs the inherited context.
 
 ## Mixins 
 
@@ -150,6 +148,18 @@ Mixins help get around the diamond problem. (TODO: write more about this)
 ## Versioning
 
 Note that the versioning of `libspec` is still being hammered
-out. Currently, the version of `libspec` appears in the generated XML
+out. Currently, the version of `libspec` appears in generated spec snapshots
 (`libspec-version` field). But, how diffs will be performed on
 different versions is unexplored.
+
+## Feature Branch & Multi-Commit Spec Diffing
+
+When working on feature branches with intermediate commits, running `uv run libspec diff` right after a commit will report `No changes detected` because `HEAD` matches the live spec on disk.
+
+To track the cumulative specification delta across all intermediate commits on a feature branch, pass the base branch target:
+
+```bash
+uv run libspec diff main
+```
+
+This tracks all specification additions, requirement modifications, and docstring changes relative to `main` throughout multi-stage development workflows.

{libspec-10.2.0 → libspec-10.3.3}/libspec/agent_config.py

@@ -91,7 +91,7 @@ class AgentConfig(abc.ABC):
         spec.mcp.AgentSkillInstallation
         """
         filename = "SKILL.md"
-        temp_file = os.path.join(dir_path, f"TEMP_{filename}")
+        temp_file = os.path.join(dir_path, f"TEMP_{os.getpid()}_{filename}")
         os.makedirs(dir_path, exist_ok=True)
 
         try:
@@ -141,7 +141,7 @@ class AgentConfig(abc.ABC):
                 json.dump(config, f, indent=2)
         except Exception as e:
             raise RuntimeError(
-                f"Config Persistence Failure: Could not write updated configuration to {path}. {e}"
+                f"Config Persistence Failure: Could not write updated JSON configuration to {path}. {e}"
             )
 
     def _load_toml_config(self, path: str) -> dict:
@@ -169,6 +169,7 @@ class AgentConfig(abc.ABC):
     @property
     def skill_dir_path(self) -> str:
         # spec.mcp.AgentSkillDriftDetection
+        # spec.agents.AgentsDirectoryLayoutReq
         if self.agent_id == "antigravity":
             return os.path.join(
                 self.project_root, ".gemini", "antigravity", "skills", "libspec"
@@ -183,11 +184,20 @@ class AgentConfig(abc.ABC):
             return os.path.join(self.project_root, ".github", "skills", "libspec")
         elif self.agent_id == "codex":
             return os.path.join(self.project_root, ".codex", "skills", "libspec")
+        elif self.agent_id == "agents":
+            primary = os.path.join(self.project_root, ".agents", "skills", "libspec")
+            legacy = os.path.join(
+                self.project_root, ".agents", "skills", "libspec-agent-workflow"
+            )
+            if not os.path.exists(primary) and os.path.exists(legacy):
+                return legacy
+            return primary
         raise ValueError(f"Unknown agent ID: {self.agent_id}")
 
     @property
     def is_active(self) -> bool:
         # spec.mcp.AgentSkillDriftDetection
+        # spec.agents.AgentsDirectoryLayoutReq
         if self.agent_id == "antigravity":
             return os.path.exists(
                 os.path.join(
@@ -212,18 +222,26 @@ class AgentConfig(abc.ABC):
             return os.path.exists(
                 os.path.join(self.project_root, ".codex", "config.toml")
             )
+        elif self.agent_id == "agents":
+            agents_path = os.path.join(self.project_root, ".agents")
+            return os.path.exists(agents_path) and os.path.isdir(agents_path)
         return False
 
     def is_skill_up_to_date(self) -> bool:
         # spec.mcp.SkillVersionValidation
+        # spec.agents.AgentsSkillDriftDetectionReq
         skill_path = os.path.join(self.skill_dir_path, "SKILL.md")
-        if not os.path.exists(skill_path):
+        if not os.path.exists(skill_path) or not os.path.isfile(skill_path):
             return False
         try:
-            current_content = self._render_skill()
             with open(skill_path, encoding="utf-8") as f:
                 installed_content = f.read()
-            return current_content == installed_content
+
+            if "libspec: disable-auto-heal" in installed_content:
+                return True
+
+            current_content = self._render_skill()
+            return current_content.strip() == installed_content.strip()
         except Exception:
             return False
 
@@ -480,6 +498,30 @@ class CodexConfig(AgentConfig):
     agent_description = "Navigation and specification tools for Codex"
 
 
+class AgentsConfig(AgentConfig):
+    """
+    Handles configuration for workspace .agents skills and setup.
+    # spec.agents.AgentsDirectoryLayoutReq
+    # spec.agents.AgentsSkillValidationReq
+    # spec.agents.AgentsSkillHealingFeat
+    """
+
+    def configure(self) -> str:
+        config_dir = os.path.join(self.project_root, ".agents")
+        if os.path.exists(config_dir) and not os.path.isdir(config_dir):
+            raise ValueError(
+                f"Path Conflict: {config_dir} exists as a file instead of a directory."
+            )
+        os.makedirs(config_dir, exist_ok=True)
+        skill_dir = self.skill_dir_path
+        self._install_skill(skill_dir, self._render_skill())
+        return f"Successfully configured .agents skill in {skill_dir}."
+
+    agent_id = "agents"
+    agent_display_name = "Agents"
+    agent_description = "Navigation and specification tools for workspace .agents"
+
+
 def list_supported_agents() -> str:
     """
     Returns a formatted list of all supported agent names.

{libspec-10.2.0 → libspec-10.3.3}/libspec/mcp_server.py

@@ -1,20 +1,13 @@
-"""
-MCP Server entry point for libspec.
-"""
-
 import ast
 import glob
 import json
 import os
 import subprocess
 import sys
-import threading
 from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
 
-from libspec.lsp_client import LspClient, LspError
-
 mcp = FastMCP(
     "libspec",
     instructions="""
@@ -23,60 +16,18 @@ mcp = FastMCP(
     This server provides specialized tools for specification-driven development 
     and deep code analysis.
     
-    ## Navigation & Search (Prefer LSP over Grep)
-    - Always prefer LSP-based tools (`search`, `peek`, `symbols`, `usage`) 
-      over generic `grep` when you need semantic understanding of the code.
+    ## Navigation & Search
     - Use `search` to find both specification components (Requirements/Features) 
       and their implementations.
     - Use `peek` to retrieve documentation and definitions for specific symbols 
       without reading entire files.
-    - Use `symbols` to orient yourself within a new file's structure.
+    - Use `symbols` to orient yourself within a file's structure.
     - Use `usage` to perform impact analysis before modifying shared components.
-    
-    ## Lifecycle
-    - The background LSP server (`pylsp`) auto-initializes on the first call to 
-      any LSP-dependent tool. No manual setup is required.
       
     spec.mcp.McpServerInstructions
     """,
 )
 
-# Global LSP client instance
-lsp = LspClient()
-lsp_lock = threading.Lock()
-
-
-def _ensure_lsp_started(requested_root: str = None):
-    """
-    Internal helper to ensure the LSP process is running.
-    Auto-starts with sensible defaults if not already initialized.
-    """
-    if lsp.process:
-        return
-
-    with lsp_lock:
-        if lsp.process:
-            return
-
-        # Default root discovery logic
-        if requested_root:
-            root_dir = requested_root
-        else:
-            root_candidates = ["spec", "."]
-            root_dir = next((d for d in root_candidates if os.path.isdir(d)), ".")
-
-        # Call start_lsp logic directly to ensure initialization
-        root_uri = _to_uri(root_dir)
-        try:
-            lsp.start(root_uri)
-        except Exception as e:
-            # spec.lsp_auto_init.DiagnosticInitialization
-            raise LspError(
-                f"Failed to auto-initialize LSP for workspace '{root_dir}'.",
-                step="auto-start",
-                details=f"Original Error: {e}\nEnsure 'python-lsp-server' is installed (e.g., `uv add --dev python-lsp-server`).",
-            )
-
 
 def _to_uri(file_path: str) -> str:
     return Path(os.path.abspath(file_path)).as_uri()
@@ -103,66 +54,28 @@ def diff(commit_a: str = None, commit_b: str = None) -> str:
         return f"Error running diff:\n{e.stderr}\n{e.stdout}"
 
 
-@mcp.tool()
-def start_lsp(root_dir: str = "spec") -> str:
-    """
-    Start the background pylsp server for the given workspace.
-    """
-    try:
-        _ensure_lsp_started(root_dir)  # Ensure idempotency and state safety
-        return f"LSP Server (pylsp) started for {root_dir}"
-    except Exception as e:
-        return f"Error starting LSP: {e}"
-
-
 @mcp.tool()
 def search(query: str) -> str:
     """
-    Perform a workspace-wide semantic search for components (classes, methods, variables).
-    This tool combines native libspec discovery for specification components with
-    LSP symbol search for general code discovery.
+    Perform a workspace-wide search for components (classes, methods, variables).
+    Uses native libspec discovery for specification components and AST parsing.
     """
     assert query, "Search query cannot be empty."
 
     results = []
 
-    # 1. Native Spec Discovery (high precision for Features/Requirements)
     try:
         results.extend(_native_spec_discovery(query))
     except Exception:
         pass
 
-    # 2. LSP Symbol Search (broader coverage for implementations)
-    try:
-        _ensure_lsp_started()
-        res = lsp.send_request("workspace/symbol", {"query": query})
-        lsp_results = res.get("result", [])
-        if lsp_results:
-            seen_locs = {
-                (
-                    r.get("location", {}).get("uri"),
-                    r.get("location", {}).get("range", {}).get("start", {}).get("line"),
-                )
-                for r in results
-                if "location" in r
-            }
-
-            for sym in lsp_results:
-                loc = sym.get("location", {})
-                uri = loc.get("uri")
-                start_line = loc.get("range", {}).get("start", {}).get("line")
-                if (uri, start_line) not in seen_locs:
-                    results.append(sym)
-    except Exception:
-        pass
-
     return json.dumps(results, indent=2)
 
 
 def _native_spec_discovery(query: str):
     """Scan the workspace for classes matching the query using AST."""
     results = []
-    patterns = ["spec/**/*.py", "*_spec.py", "spec.py"]
+    patterns = ["spec/**/*.py", "*_spec.py", "spec.py", "libspec/**/*.py"]
     files = []
     for p in patterns:
         files.extend(glob.glob(p, recursive=True))
@@ -175,7 +88,9 @@ def _native_spec_discovery(query: str):
             with open(path, encoding="utf-8") as f:
                 tree = ast.parse(f.read())
             for node in ast.walk(tree):
-                if isinstance(node, ast.ClassDef):
+                if isinstance(
+                    node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+                ):
                     docstring = ast.get_docstring(node) or ""
                     if (
                         query_lower in node.name.lower()
@@ -184,13 +99,13 @@ def _native_spec_discovery(query: str):
                         results.append(
                             {
                                 "name": node.name,
-                                "kind": 5,  # Class
+                                "kind": 5 if isinstance(node, ast.ClassDef) else 12,
                                 "location": {
                                     "uri": Path(os.path.abspath(path)).as_uri(),
                                     "range": {
                                         "start": {
                                             "line": node.lineno - 1,
-                                            "character": 0,
+                                            "character": node.col_offset,
                                         },
                                         "end": {
                                             "line": (
@@ -220,18 +135,43 @@ def peek(file_path: str, line: int, character: int) -> str:
     assert character >= 0, "Character offset must be non-negative."
 
     try:
-        _ensure_lsp_started()
-        uri = _to_uri(file_path)
-        pos = {"line": line, "character": character}
-
-        hover = lsp.send_request(
-            "textDocument/hover", {"textDocument": {"uri": uri}, "position": pos}
-        )
-        definition = lsp.send_request(
-            "textDocument/definition", {"textDocument": {"uri": uri}, "position": pos}
-        )
-
-        result = {"hover": hover.get("result"), "definition": definition.get("result")}
+        with open(file_path, encoding="utf-8") as f:
+            source = f.read()
+        tree = ast.parse(source)
+        target_node = None
+        target_line = line + 1
+        for node in ast.walk(tree):
+            if hasattr(node, "lineno"):
+                end_lineno = getattr(node, "end_lineno", node.lineno)
+                if node.lineno <= target_line <= end_lineno:
+                    if isinstance(
+                        node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+                    ):
+                        target_node = node
+
+        if target_node:
+            docstring = ast.get_docstring(target_node) or ""
+            result = {
+                "hover": f"**{target_node.name}**\n\n{docstring}".strip(),
+                "definition": {
+                    "uri": Path(os.path.abspath(file_path)).as_uri(),
+                    "range": {
+                        "start": {
+                            "line": target_node.lineno - 1,
+                            "character": target_node.col_offset,
+                        },
+                        "end": {
+                            "line": (
+                                getattr(target_node, "end_lineno", target_node.lineno)
+                            )
+                            - 1,
+                            "character": 0,
+                        },
+                    },
+                },
+            }
+        else:
+            result = {"hover": "", "definition": {}}
         return json.dumps(result, indent=2)
     except Exception as e:
         return f"Navigation Failure: Failed to peek at {file_path}:{line}:{character}.\n{e}"
@@ -240,24 +180,11 @@ def peek(file_path: str, line: int, character: int) -> str:
 @mcp.tool()
 def usage(file_path: str, line: int, character: int) -> str:
     """
-    Find all semantic references to a component.
+    Find references to a component.
     """
     assert os.path.exists(file_path), f"File not found: {file_path}"
 
-    try:
-        _ensure_lsp_started()
-        uri = _to_uri(file_path)
-        res = lsp.send_request(
-            "textDocument/references",
-            {
-                "textDocument": {"uri": uri},
-                "position": {"line": line, "character": character},
-                "context": {"includeDeclaration": True},
-            },
-        )
-        return json.dumps(res.get("result", []), indent=2)
-    except Exception as e:
-        return f"Impact Analysis Failure: Could not find references for component at {file_path}:{line}.\n{e}"
+    return json.dumps([], indent=2)
 
 
 @mcp.tool()
@@ -268,76 +195,38 @@ def symbols(file_path: str) -> str:
     assert os.path.exists(file_path), f"File not found: {file_path}"
 
     try:
-        _ensure_lsp_started()
-        uri = _to_uri(file_path)
-        res = lsp.send_request(
-            "textDocument/documentSymbol", {"textDocument": {"uri": uri}}
-        )
-        return json.dumps(res.get("result", []), indent=2)
+        with open(file_path, encoding="utf-8") as f:
+            tree = ast.parse(f.read())
+        results = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+                docstring = ast.get_docstring(node) or ""
+                results.append(
+                    {
+                        "name": node.name,
+                        "kind": 5 if isinstance(node, ast.ClassDef) else 12,
+                        "location": {
+                            "uri": Path(os.path.abspath(file_path)).as_uri(),
+                            "range": {
+                                "start": {
+                                    "line": node.lineno - 1,
+                                    "character": node.col_offset,
+                                },
+                                "end": {
+                                    "line": (getattr(node, "end_lineno", node.lineno))
+                                    - 1,
+                                    "character": 0,
+                                },
+                            },
+                        },
+                        "description": docstring.strip(),
+                    }
+                )
+        return json.dumps(results, indent=2)
     except Exception as e:
         return f"Structural Analysis Failure: Failed to list components in {file_path}.\n{e}"
 
 
-@mcp.tool()
-def pylsp_plugin(plugin_name: str, action: str = "status") -> str:
-    """
-    Control any pylsp plugin (e.g., "hello", "pyflakes").
-
-    Args:
-        plugin_name: The name of the plugin to control.
-        action: "status", "enable", or "disable". Defaults to "status".
-    """
-    # spec.hello_plugin.PluginMcpControl
-    # spec.mcp.McpPylspPluginTool
-    try:
-        _ensure_lsp_started()
-
-        if action == "status":
-            return f"Plugin '{plugin_name}' is currently managed via LSP workspace configuration."
-
-        enabled = action == "enable"
-
-        # Update workspace configuration dynamically
-        lsp.send_notification(
-            "workspace/didChangeConfiguration",
-            {"settings": {"plugins": {plugin_name: {"enabled": enabled}}}},
-        )
-
-        return (
-            f"Plugin '{plugin_name}' has been {'enabled' if enabled else 'disabled'}."
-        )
-    except Exception as e:
-        return f"Error controlling plugin '{plugin_name}': {e}"
-
-
-@mcp.tool()
-def set_pylsp_plugin_setting(plugin_name: str, setting_name: str, value: str) -> str:
-    """
-    Set an arbitrary configuration value for a pylsp plugin dynamically.
-
-    Args:
-        plugin_name: The name of the plugin (e.g., "hello_ast").
-        setting_name: The specific setting key to update (e.g., "pattern").
-        value: The value to apply (will be parsed as JSON if possible, otherwise treated as a string).
-    """
-    try:
-        _ensure_lsp_started()
-
-        try:
-            parsed_value = json.loads(value)
-        except Exception:
-            parsed_value = value
-
-        lsp.send_notification(
-            "workspace/didChangeConfiguration",
-            {"settings": {"plugins": {plugin_name: {setting_name: parsed_value}}}},
-        )
-
-        return f"Successfully updated '{plugin_name}.{setting_name}' to {repr(parsed_value)}."
-    except Exception as e:
-        return f"Error updating setting for plugin '{plugin_name}': {e}"
-
-
 @mcp.tool()
 def mcp_agent(
     agent: str = None, project_root: str = ".", list_agents: bool = False
@@ -520,12 +409,6 @@ def agent_workflow(agent: str = None, prefix: str = None) -> str:
     return get_agent_workflow(pfx)
 
 
-try:
-    import libspec_scheduler.mcp
-except ImportError:
-    pass
-
-
 def main():
     try:
         from libspec.agent_config import check_and_heal_skills