invar-tools 1.17.7__py3-none-any.whl → 1.17.8__py3-none-any.whl

invar/mcp/handlers.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 from typing import Any, Literal
 
+from mcp.server.lowlevel.server import StructuredContent, CombinationContent
 from mcp.types import TextContent
 from returns.result import Success
 
@@ -59,7 +60,7 @@ def _validate_path(path: str) -> tuple[bool, str]:
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @shell_complexity: Guard command with multiple optional flags
 # @invar:allow shell_result: MCP handler for guard tool
-async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
+async def _run_guard(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar guard command."""
     path = args.get("path", ".")
     is_valid, error = _validate_path(path)
@@ -88,7 +89,7 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @invar:allow shell_result: MCP handler for sig tool
-async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
+async def _run_sig(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar sig command."""
     target = args.get("target", "")
     if not target:
@@ -106,7 +107,7 @@ async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @invar:allow shell_result: MCP handler for map tool
-async def _run_map(args: dict[str, Any]) -> list[TextContent]:
+async def _run_map(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar map command."""
     path = args.get("path", ".")
     is_valid, error = _validate_path(path)
@@ -125,7 +126,7 @@ async def _run_map(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - orchestrates refs command execution
 # @invar:allow shell_result: MCP handler for refs tool
-async def _run_refs(args: dict[str, Any]) -> list[TextContent]:
+async def _run_refs(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar refs command.
 
     DX-78: Find all references to a symbol.
@@ -155,7 +156,7 @@ async def _run_refs(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_toc tool
-async def _run_doc_toc(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_toc(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_toc - extract document structure."""
     from dataclasses import asdict
 
@@ -203,7 +204,7 @@ def _section_to_dict(section: Any) -> dict[str, Any]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_read tool
-async def _run_doc_read(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_read(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_read - read a specific section."""
     from invar.shell.doc_tools import read_section
 
@@ -232,7 +233,7 @@ async def _run_doc_read(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_complexity: Multiple arg validation branches + error handling
 # @invar:allow shell_result: MCP handler for doc_read_many tool
-async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_read_many - read multiple sections."""
     from invar.shell.doc_tools import read_sections_batch
 
@@ -264,7 +265,7 @@ async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_find tool
-async def _run_doc_find(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_find(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_find - find sections matching pattern."""
     from invar.shell.doc_tools import find_sections
 
@@ -308,7 +309,7 @@ async def _run_doc_find(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_replace tool
-async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_replace - replace section content."""
     from invar.shell.doc_tools import replace_section_content
 
@@ -342,7 +343,7 @@ async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_insert tool
-async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_insert - insert content relative to section."""
     from invar.shell.doc_tools import insert_section_content
 
@@ -382,7 +383,7 @@ async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_delete tool
-async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_delete - delete a section."""
     from invar.shell.doc_tools import delete_section_content
 
@@ -411,13 +412,11 @@ async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_complexity: Command execution with error handling branches
 # @invar:allow shell_result: MCP subprocess wrapper utility
-async def _execute_command(cmd: list[str], timeout: int = 600) -> list[TextContent]:
-    """Execute a command and return the result.
-
-    Args:
-        cmd: Command to execute
-        timeout: Maximum time in seconds (default: 600, accommodates full Guard cycle)
-    """
+async def _execute_command(
+    cmd: list[str],
+    timeout: int = 600,
+) -> list[TextContent] | CombinationContent:
+    """Execute a command and return result."""
     try:
         result = subprocess.run(
             cmd,
@@ -426,20 +425,16 @@ async def _execute_command(cmd: list[str], timeout: int = 600) -> list[TextConte
             timeout=timeout,
         )
 
-        output = result.stdout
-        if result.stderr:
-            output += f"\n\nStderr:\n{result.stderr}"
-
-        # Try to parse as JSON for better formatting
         try:
             parsed = json.loads(result.stdout)
-            output = json.dumps(parsed, indent=2)
+            return ([TextContent(type="text", text=json.dumps(parsed, indent=2))], parsed)
         except json.JSONDecodeError:
-            pass
-
-        return [TextContent(type="text", text=output)]
+            output = result.stdout
+            if result.stderr:
+                output += f"\n\nStderr:\n{result.stderr}"
+            return [TextContent(type="text", text=output)]
 
     except subprocess.TimeoutExpired:
-        return [TextContent(type="text", text=f"Error: Command timed out ({timeout}s)")]
+        return [TextContent(type="text", text=f"Error: Command timed out ({timeout}s")]
     except Exception as e:
         return [TextContent(type="text", text=f"Error: {e}")]

invar/shell/commands/guard.py

@@ -15,12 +15,6 @@ from rich.console import Console
 from rich.table import Table
 
 
-def _detect_agent_mode() -> bool:
-    """Detect agent context: INVAR_MODE=agent OR non-TTY (pipe/redirect)."""
-    import sys
-    return os.getenv("INVAR_MODE") == "agent" or not sys.stdout.isatty()
-
-
 from invar import __version__
 from invar.core.models import GuardReport, RuleConfig
 from invar.core.rules import check_all_rules
@@ -95,12 +89,14 @@ def _scan_and_check(
             for rule, reason, line in extract_escape_hatches(file_info.source):
                 all_escapes.append((file_info.path, rule, reason))
                 # DX-66: Add to escape hatch summary
-                report.escape_hatches.add(EscapeHatchDetail(
-                    file=file_info.path,
-                    line=line,
-                    rule=rule,
-                    reason=reason,
-                ))
+                report.escape_hatches.add(
+                    EscapeHatchDetail(
+                        file=file_info.path,
+                        line=line,
+                        rule=rule,
+                        reason=reason,
+                    )
+                )
 
     # DX-22: Check project-level complexity debt (Fix-or-Explain enforcement)
     for debt_violation in check_complexity_debt(
@@ -133,7 +129,7 @@ def guard(
         False, "--static", help="Static analysis only, skip all runtime tests"
     ),
     human: bool = typer.Option(
-        False, "--human", help="Force human-readable output (for testing/debugging)"
+        False, "--human", help="Force Rich human-readable output (opt-in, default is JSON)"
     ),
     # DX-26: Deprecated flags kept for backward compatibility
     no_strict_pure: bool = typer.Option(
@@ -192,23 +188,12 @@ def guard(
         ts_result = run_typescript_guard(path if path.is_dir() else find_project_root(path))
         match ts_result:
             case Success(result):
-                if json_output or agent:
-                    import json as json_mod
-
-                    from invar.shell.prove.guard_ts import format_typescript_guard_v2
-
-                    output = format_typescript_guard_v2(result)
-                    console.print(json_mod.dumps(output, indent=2))
-                else:
-                    console.print(f"[bold]TypeScript Guard[/bold] ({project_language})")
-                    if result.status == "passed":
-                        console.print("[green]✓ PASSED[/green]")
-                    elif result.status == "skipped":
-                        console.print("[yellow]⚠ SKIPPED[/yellow] (no TypeScript tools available)")
-                    else:
-                        console.print(f"[red]✗ FAILED[/red] ({result.error_count} errors)")
-                        for v in result.violations[:10]:  # Show first 10
-                            console.print(f"  {v.file}:{v.line}: [{v.severity}] {v.message}")
+                import json as json_mod
+
+                from invar.shell.prove.guard_ts import format_typescript_guard_v2
+
+                output = format_typescript_guard_v2(result)
+                console.print(json_mod.dumps(output, indent=2))
                 raise typer.Exit(0 if result.status == "passed" else 1)
             case Failure(err):
                 console.print(f"[red]Error:[/red] {err}")
@@ -295,6 +280,7 @@ def guard(
             run_pattern_detection,
             suggestions_to_violations,
         )
+
         # Run pattern detection on checked files
         files_to_check = list(only_files) if only_files else None
         pattern_result = run_pattern_detection(path, files_to_check)
@@ -331,6 +317,7 @@ def guard(
     # DX-37: Check coverage availability if requested
     if coverage:
         from invar.shell.coverage import check_coverage_available
+
         cov_check = check_coverage_available()
         if isinstance(cov_check, Failure):
             console.print(f"[yellow]Warning:[/yellow] {cov_check.failure()}")
@@ -342,14 +329,19 @@ def guard(
 
         # Phase 1: Doctests (DX-37: with optional coverage)
         doctest_passed, doctest_output, doctest_coverage = run_doctests_phase(
-            checked_files, explain, timeout=config.timeout_doctest,
+            checked_files,
+            explain,
+            timeout=config.timeout_doctest,
             collect_coverage=coverage,
         )
 
         # Phase 2: CrossHair symbolic verification
         # Note: CrossHair uses subprocess + symbolic execution, coverage not applicable
         crosshair_passed, crosshair_output = run_crosshair_phase(
-            path, checked_files, doctest_passed, static_exit_code,
+            path,
+            checked_files,
+            doctest_passed,
+            static_exit_code,
             changed_mode=changed,
             timeout=config.timeout_crosshair,
             per_condition_timeout=config.timeout_crosshair_per_condition,
@@ -357,7 +349,9 @@ def guard(
 
         # Phase 3: Hypothesis property tests (DX-37: with optional coverage)
         property_passed, property_output, property_coverage = run_property_tests_phase(
-            checked_files, doctest_passed, static_exit_code,
+            checked_files,
+            doctest_passed,
+            static_exit_code,
             collect_coverage=coverage,
         )
     elif verification_level == VerificationLevel.STATIC:
@@ -382,20 +376,31 @@ def guard(
         if property_coverage and property_coverage.get("collected"):
             coverage_output["phases_tracked"].append("hypothesis")
             if "overall_branch_coverage" in property_coverage:
-                coverage_output["overall_branch_coverage"] = property_coverage["overall_branch_coverage"]
+                coverage_output["overall_branch_coverage"] = property_coverage[
+                    "overall_branch_coverage"
+                ]
 
     # DX-26: Unified output (agent JSON or human Rich)
     if use_agent_output:
         output_agent(
-            report, strict, doctest_passed, doctest_output, crosshair_output, level_name,
+            report,
+            strict,
+            doctest_passed,
+            doctest_output,
+            crosshair_output,
+            level_name,
             property_output=property_output,
             coverage_data=coverage_output,  # DX-37
         )
     else:
         output_rich(report, config.strict_pure, changed, pedantic, explain, static)
         output_verification_status(
-            verification_level, static_exit_code, doctest_passed,
-            doctest_output, crosshair_output, explain,
+            verification_level,
+            static_exit_code,
+            doctest_passed,
+            doctest_output,
+            crosshair_output,
+            explain,
             property_output=property_output,
             strict=strict,
         )
@@ -405,7 +410,9 @@ def guard(
             overall = coverage_output.get("overall_branch_coverage", 0.0)
             console.print(f"\n[bold]Coverage Analysis[/bold] ({' + '.join(phases)})")
             console.print(f"  Overall branch coverage: {overall}%")
-            console.print("  [dim]Note: CrossHair uses symbolic execution; coverage not applicable.[/dim]")
+            console.print(
+                "  [dim]Note: CrossHair uses symbolic execution; coverage not applicable.[/dim]"
+            )
 
     # Exit with combined status
     all_passed = doctest_passed and crosshair_passed and property_passed
@@ -415,24 +422,23 @@ def guard(
 
 # @shell_orchestration: Output mode decision helper for CLI
 def _determine_output_mode(human: bool, agent: bool = False, json_output: bool = False) -> bool:
-    """Determine if agent JSON output should be used (DX-26).
+    """Determine if agent JSON output should be used (Agent First).
 
-    DX-26: TTY auto-detection with --human override.
-    - --human flag → human output (for testing/debugging)
-    - TTY (terminal) → human output
-    - Non-TTY (pipe/redirect) → agent JSON output
-    - Deprecated --agent/--json flags → still work for backward compat
+    Agent First principle: Machine-readable JSON is the default output format.
+    Human-readable Rich output is opt-in via --human flag.
+
+    Priority:
+    - --human flag → human output (Rich, colored)
+    - Default → JSON output (machine-readable, Agent Native)
+    - --agent/--json flags → no-op (already default, kept for backward compat)
     """
-    # --human flag always forces human output
+    # --human flag forces human output (priority highest)
     if human:
         return False  # use_agent = False
 
-    # Deprecated flags (backward compat)
-    if json_output or agent:
-        return True  # use_agent = True
-
-    # TTY auto-detection
-    return _detect_agent_mode()  # Returns True if non-TTY
+    # Default to JSON output (Agent First)
+    # --agent/--json are now no-ops but kept for backward compatibility
+    return True
 
 
 def _show_verification_level(verification_level) -> None:
@@ -464,8 +470,9 @@ def map_command(
     """Generate symbol map with reference counts."""
     from invar.shell.commands.perception import run_map
 
-    # Phase 9 P11: Auto-detect agent mode
-    use_json = json_output or _detect_agent_mode()
+    # Agent First: Default to JSON output
+    # --json is now a no-op (kept for backward compat)
+    use_json = True
     result = run_map(path, top, use_json)
     if isinstance(result, Failure):
         console.print(f"[red]Error:[/red] {result.failure()}")
@@ -480,8 +487,9 @@ def sig_command(
     """Extract signatures from a file or symbol."""
     from invar.shell.commands.perception import run_sig
 
-    # Phase 9 P11: Auto-detect agent mode
-    use_json = json_output or _detect_agent_mode()
+    # Agent First: Default to JSON output
+    # --json is now a no-op (kept for backward compat)
+    use_json = True
     result = run_sig(target, use_json)
     if isinstance(result, Failure):
         console.print(f"[red]Error:[/red] {result.failure()}")
@@ -504,8 +512,9 @@ def refs_command(
     """
     from invar.shell.commands.perception import run_refs
 
-    # Auto-detect agent mode
-    use_json = json_output or _detect_agent_mode()
+    # Agent First: Default to JSON output
+    # --json is now a no-op (kept for backward compat)
+    use_json = True
     result = run_refs(target, use_json)
     if isinstance(result, Failure):
         console.print(f"[red]Error:[/red] {result.failure()}")
@@ -529,8 +538,9 @@ def rules(
 
     from invar.core.rule_meta import RULE_META, RuleCategory, get_rules_by_category
 
-    # Phase 9 P11: Auto-detect agent mode
-    use_json = json_output or _detect_agent_mode()
+    # Agent First: Default to JSON output
+    # --json is now a no-op (kept for backward compat)
+    use_json = True
 
     # Filter by category if specified
     if category:

{invar_tools-1.17.7.dist-info → invar_tools-1.17.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.17.7
+Version: 1.17.8
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme

{invar_tools-1.17.7.dist-info → invar_tools-1.17.8.dist-info}/RECORD

@@ -50,7 +50,7 @@ invar/core/patterns/registry.py,sha256=2rz0wWDRarMkuHN-qM_ZrT3qeGFDSKMABvRvPNZxQ
 invar/core/patterns/types.py,sha256=ULAlWuAdmO6CFcEDjTrWBfzNTBsnomAl2d25tR11ihU,5506
 invar/mcp/__init__.py,sha256=n3S7QwMjSMqOMT8cI2jf9E0yZPjKmBOJyIYhq4WZ8TQ,226
 invar/mcp/__main__.py,sha256=ZcIT2U6xUyGOWucl4jq422BDE3lRLjqyxb9pFylRBdk,219
-invar/mcp/handlers.py,sha256=Kls1aXnYmGcMvib_Mesfz5FjBaL7lmrhKaw_P2JDnyw,16551
+invar/mcp/handlers.py,sha256=gutZuiukdfANWJliRtqX0xV7__MDwMs8C1U3H-R_hDs,16736
 invar/mcp/server.py,sha256=zSpY9bCFuq4mWe7XfolTnwHffhdmoyN40aFL4L7dFrE,20407
 invar/node_tools/.gitignore,sha256=M2kz8Iw7Kzmi44mKo1r7_HOZMh79a7dFDdRrqXyaEhI,530
 invar/node_tools/MANIFEST,sha256=2Z2at-27MK8K7DSjOjjtR4faTbt6eCiKQuEfvP_lwH8,145
@@ -2681,7 +2681,7 @@ invar/shell/ts_compiler.py,sha256=nA8brnOhThj9J_J3vAEGjDsM4NjbWQ_eX8Yf4pHPOgk,66
 invar/shell/commands/__init__.py,sha256=MEkKwVyjI9DmkvBpJcuumXo2Pg_FFkfEr-Rr3nrAt7A,284
 invar/shell/commands/doc.py,sha256=SOLDoCXXGxx_JU0PKXlAIGEF36PzconHmmAtL-rM6D4,13819
 invar/shell/commands/feedback.py,sha256=lLxEeWW_71US_vlmorFrGXS8IARB9nbV6D0zruLs660,7640
-invar/shell/commands/guard.py,sha256=ZuqxYkCZHoomUPuk4-HNf0bTk86il0_uRkhOTvD6T3k,24840
+invar/shell/commands/guard.py,sha256=oVx8h0YVxngfvEiuSmSuDTuXXKpzBzOHz5_5nD8_Ua4,24374
 invar/shell/commands/hooks.py,sha256=W-SOnT4VQyUvXwipozkJwgEYfiOJGz7wksrbcdWegUg,2356
 invar/shell/commands/init.py,sha256=rtoPFsfq7xRZ6lfTipWT1OejNK5wfzqu1ncXi1kizU0,23634
 invar/shell/commands/merge.py,sha256=nuvKo8m32-OL-SCQlS4SLKmOZxQ3qj-1nGCx1Pgzifw,8183
@@ -2778,10 +2778,10 @@ invar/templates/skills/invar-reflect/template.md,sha256=Rr5hvbllvmd8jSLf_0ZjyKt6
 invar/templates/skills/investigate/SKILL.md.jinja,sha256=cp6TBEixBYh1rLeeHOR1yqEnFqv1NZYePORMnavLkQI,3231
 invar/templates/skills/propose/SKILL.md.jinja,sha256=6BuKiCqO1AEu3VtzMHy1QWGqr_xqG9eJlhbsKT4jev4,3463
 invar/templates/skills/review/SKILL.md.jinja,sha256=ET5mbdSe_eKgJbi2LbgFC-z1aviKcHOBw7J5Q28fr4U,14105
-invar_tools-1.17.7.dist-info/METADATA,sha256=v4uFpW9-ouRRiRqmkIR-GRWDTDsLa5304LnjooU67sA,28595
-invar_tools-1.17.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-invar_tools-1.17.7.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
-invar_tools-1.17.7.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
-invar_tools-1.17.7.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
-invar_tools-1.17.7.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
-invar_tools-1.17.7.dist-info/RECORD,,
+invar_tools-1.17.8.dist-info/METADATA,sha256=2wbwXUo9G-81P-Riuv9WTYBY06Yiihint4wbdIvlJoE,28595
+invar_tools-1.17.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+invar_tools-1.17.8.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
+invar_tools-1.17.8.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
+invar_tools-1.17.8.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
+invar_tools-1.17.8.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
+invar_tools-1.17.8.dist-info/RECORD,,