codegraphcontext 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

codegraphcontext/api/app.py

@@ -4,9 +4,14 @@ from fastapi import FastAPI
 from fastapi.responses import HTMLResponse
 from fastapi.middleware.cors import CORSMiddleware
 from .router import router
+from .auth import log_auth_status
 from .mcp_sse import handle_sse, handle_messages
 
 def create_app() -> FastAPI:
+    # Log whether API-key auth is active. Emits a prominent security warning
+    # when the gateway is running unauthenticated (CGC_API_KEY unset).
+    log_auth_status()
+
     app = FastAPI(
         title="CodeGraphContext Gateway",
         description="HTTP API gateway for CodeGraphContext MCP server. Enables integration with ChatGPT Actions, Claude, and web frontends.",
@@ -61,7 +66,7 @@ def create_app() -> FastAPI:
                     <a href="/docs" class="btn">View API Docs</a>
                     <div class="links">
                         <a href="/openapi.json">OpenAPI Spec</a>
-                        <a href="https://github.com/Shashankss1205/CodeGraphContext" target="_blank">GitHub</a>
+                        <a href="https://github.com/CodeGraphContext/CodeGraphContext" target="_blank">GitHub</a>
                     </div>
                 </div>
             </body>

codegraphcontext/api/auth.py

@@ -0,0 +1,123 @@
+# src/codegraphcontext/api/auth.py
+"""Optional API-key authentication for the CodeGraphContext HTTP API.
+
+Backward-compatible and opt-in:
+
+* When **no** key is configured, the API behaves exactly as it did before
+  (every endpoint is unauthenticated) but a prominent security warning is
+  logged at startup so operators know the gateway is wide open.
+* When a key **is** configured (via the ``CGC_API_KEY`` environment variable
+  or the standard config mechanism), every protected router endpoint requires
+  it, supplied as either ``Authorization: Bearer <key>`` or ``X-API-Key: <key>``.
+  Missing/incorrect keys receive an HTTP ``401``.
+
+The comparison uses :func:`secrets.compare_digest` to avoid timing side
+channels.
+"""
+
+import logging
+import os
+import secrets
+from typing import Optional
+
+from fastapi import Header, HTTPException
+
+logger = logging.getLogger(__name__)
+
+# Config/env key that holds the API key. Reused as the config_manager key so
+# ``cgc config set CGC_API_KEY <value>`` works as well.
+API_KEY_ENV = "CGC_API_KEY"
+
+
+def get_configured_api_key() -> Optional[str]:
+    """Return the configured API key, or ``None`` when auth is disabled.
+
+    Resolution order (highest priority first):
+
+    1. The ``CGC_API_KEY`` environment variable (read directly so auth works
+       even when no config file is present).
+    2. The value stored via the existing config mechanism
+       (:func:`codegraphcontext.cli.config_manager.get_config_value`).
+
+    Empty / whitespace-only values are treated as "not configured".
+    """
+    env_val = os.getenv(API_KEY_ENV)
+    if env_val and env_val.strip():
+        return env_val.strip()
+
+    # Fall back to the existing config mechanism (global/local .env, defaults).
+    try:
+        from codegraphcontext.cli.config_manager import get_config_value
+
+        cfg_val = get_config_value(API_KEY_ENV)
+        if cfg_val and cfg_val.strip():
+            return cfg_val.strip()
+    except Exception:  # pragma: no cover - config lookup is best-effort here
+        pass
+
+    return None
+
+
+def _extract_provided_key(
+    authorization: Optional[str], x_api_key: Optional[str]
+) -> Optional[str]:
+    """Pull the caller-supplied key from the Authorization or X-API-Key header."""
+    if authorization:
+        value = authorization.strip()
+        if value.lower().startswith("bearer "):
+            return value[len("bearer ") :].strip()
+        # Accept a bare token in the Authorization header as a convenience.
+        return value or None
+    if x_api_key and x_api_key.strip():
+        return x_api_key.strip()
+    return None
+
+
+def _keys_match(provided: str, configured: str) -> bool:
+    """Constant-time comparison that never raises on non-ASCII input."""
+    try:
+        return secrets.compare_digest(
+            provided.encode("utf-8"), configured.encode("utf-8")
+        )
+    except (TypeError, AttributeError):
+        return False
+
+
+async def require_api_key(
+    authorization: Optional[str] = Header(default=None),
+    x_api_key: Optional[str] = Header(default=None, alias="X-API-Key"),
+) -> None:
+    """FastAPI dependency that enforces the API key when one is configured.
+
+    No-op (backward compatible) when no key is set; otherwise requires a valid
+    key via ``Authorization: Bearer <key>`` or ``X-API-Key: <key>``, returning
+    HTTP ``401`` on a missing or incorrect key.
+    """
+    configured = get_configured_api_key()
+    if not configured:
+        # Auth disabled -> preserve the pre-existing unauthenticated behavior.
+        return
+
+    provided = _extract_provided_key(authorization, x_api_key)
+    if not provided or not _keys_match(provided, configured):
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or missing API key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def log_auth_status() -> None:
+    """Log the authentication status at app startup.
+
+    Emits a prominent WARNING when the API is unauthenticated so the insecure
+    default is impossible to miss in logs.
+    """
+    if get_configured_api_key():
+        logger.info("API key authentication is ENABLED (CGC_API_KEY is set).")
+    else:
+        logger.warning(
+            "⚠️  CodeGraphContext API is running WITHOUT authentication. "
+            "Anyone who can reach this server can index code, run Cypher queries "
+            "and call tools. Set CGC_API_KEY to require a key."
+        )

codegraphcontext/api/mcp_sse.py

@@ -1,15 +1,18 @@
 # src/codegraphcontext/api/mcp_sse.py
 import json
 import asyncio
-from fastapi import Request
+import logging
+import anyio
+from fastapi import Request, Response
 from mcp.server import Server
 from mcp.server.models import InitializationOptions
 from mcp.types import Tool, TextContent, ServerCapabilities, ToolsCapability
 from mcp.server.sse import SseServerTransport
-
 from codegraphcontext.api.router import get_server
 from codegraphcontext.server import _strip_workspace_prefix, _apply_response_token_limit
 
+logger = logging.getLogger(__name__)
+
 # Create the MCP Server instance using the SDK
 mcp_server = Server("CodeGraphContext")
 
@@ -32,38 +35,71 @@ async def handle_call_tool(name: str, arguments: dict | None) -> list[TextConten
     server = get_server()
     args = arguments or {}
     
-    # Execute via the existing handler logic
     result = await server.handle_tool_call(name, args)
     result = _strip_workspace_prefix(result)
     
     if "error" in result:
         return [TextContent(type="text", text=f"Error: {result['error']}")]
     
-    # Format result as JSON string for the AI, with the same token budget
-    # the stdio transport applies.
     response_text = json.dumps(result, indent=2)
     response_text = _apply_response_token_limit(name, response_text)
     return [TextContent(type="text", text=response_text)]
 
-# Create the SSE transport. 
-# The messages_url is where the client will POST JSON-RPC messages.
+# Create the SSE transport.
 sse = SseServerTransport("/api/v1/mcp/messages")
 
 async def handle_sse(request: Request):
     """Entry point for the SSE connection."""
-    async with sse.connect_sse(request.scope, request.receive, request._send) as (read_stream, write_stream):
-        await mcp_server.run(
-            read_stream,
-            write_stream,
-            InitializationOptions(
-                server_name="CodeGraphContext",
-                server_version="0.1.0",
-                capabilities=ServerCapabilities(
-                    tools=ToolsCapability(listChanged=False)
+    logger.info("SSE client connected")
+    try:
+        async with sse.connect_sse(request.scope, request.receive, request._send) as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name="CodeGraphContext",
+                    server_version="0.1.0",
+                    capabilities=ServerCapabilities(
+                        tools=ToolsCapability(listChanged=False)
+                    )
                 )
             )
-        )
+    except anyio.EndOfStream:
+        logger.debug("SSE client disconnected cleanly (stream ended)")
+    except Exception as exc:
+        logger.debug("SSE connection closed: %s", type(exc).__name__)
+    finally:
+        logger.info("SSE client disconnected — handler exited, resources freed")
+
 
 async def handle_messages(request: Request):
-    """Endpoint for receiving messages from the client."""
-    await sse.handle_post_message(request.scope, request.receive, request._send)
+    """Endpoint for receiving messages from the client.
+
+    Uses a buffer framing collector to ensure the full JSON-RPC payload
+    is received before processing. This prevents crashes caused by large
+    responses being split across SSE line boundaries.
+    """
+    # Buffer the complete request body before any parsing occurs.
+    # request.body() accumulates all chunks, preventing partial JSON reads.
+    raw_body = await request.body()
+
+    try:
+        json.loads(raw_body)
+    except json.JSONDecodeError as e:
+        return Response(
+            content=json.dumps({
+                "jsonrpc": "2.0",
+                "error": {
+                    "code": -32700,
+                    "message": f"Parse error: incomplete or malformed JSON-RPC message: {e}"
+                },
+                "id": None
+            }),
+            status_code=400,
+            media_type="application/json"
+        )
+
+    try:
+        await sse.handle_post_message(request.scope, request.receive, request._send)
+    except Exception as exc:
+        logger.debug("Message handler closed: %s", type(exc).__name__)

codegraphcontext/api/router.py

@@ -5,17 +5,21 @@ from typing import Dict, Any, List
 from pathlib import Path
 
 from .schemas import (
-    IndexRequest, 
-    QueryRequest, 
-    SearchRequest, 
-    ToolCallRequest, 
+    IndexRequest,
+    QueryRequest,
+    SearchRequest,
+    ToolCallRequest,
     ApiResponse
 )
+from .auth import require_api_key
 from codegraphcontext.server import MCPServer
 
 import socket
 
-router = APIRouter()
+# Optional API-key auth is enforced on every route below via require_api_key.
+# It is a no-op (backward compatible) unless CGC_API_KEY is configured, in
+# which case each request must supply the key. See codegraphcontext.api.auth.
+router = APIRouter(dependencies=[Depends(require_api_key)])
 
 # Global server instance (initialized on startup)
 _server_instance: MCPServer = None

codegraphcontext/cli/cli_helpers.py

@@ -9,6 +9,7 @@ import time
 import os
 from typing import Optional, List, Dict, Any
 import typer
+from rich import box
 from rich.console import Console
 from rich.table import Table
 from rich.progress import (
@@ -85,6 +86,45 @@ def _print_call_resolution_diagnostics(graph_builder: GraphBuilder, limit: int =
     console.print(table)
 
 
+def _format_extension_counts(files_by_extension: Dict[str, int]) -> str:
+    if not files_by_extension:
+        return "None"
+    return ", ".join(
+        f"{extension}: {count}" for extension, count in files_by_extension.items()
+    )
+
+
+def _print_index_execution_summary(graph_builder: GraphBuilder) -> None:
+    summary = getattr(graph_builder, "last_index_summary", None)
+    if not summary:
+        return
+
+    table = Table(
+        title="CGC Index Execution Summary",
+        show_header=True,
+        header_style="bold cyan",
+        box=box.ASCII,
+    )
+    table.add_column("Metric", style="cyan", no_wrap=True)
+    table.add_column("Value", style="green", overflow="fold")
+    table.add_row("Total scanned files", str(summary.get("total_scanned_files", 0)))
+    table.add_row(
+        "Files by extension",
+        _format_extension_counts(summary.get("files_by_extension", {})),
+    )
+    failed_files = summary.get("failed_files", 0)
+    if failed_files:
+        table.add_row("[red]Files failed to parse[/red]", f"[red]{failed_files}[/red]")
+    table.add_row("Function nodes", str(summary.get("function_nodes", 0)))
+    table.add_row("Class nodes", str(summary.get("class_nodes", 0)))
+    table.add_row("CALLS edges", str(summary.get("call_edges", 0)))
+    table.add_row(
+        "Serialization seconds",
+        f"{summary.get('serialization_seconds', 0.0):.2f}",
+    )
+    console.print(table)
+
+
 def _initialize_services(
     cli_context_flag: Optional[str] = None,
     cwd: Optional[Path] = None,
@@ -315,7 +355,8 @@ def index_helper(path: str, context: Optional[str] = None):
         time_end = time.time()
         elapsed = time_end - time_start
         _print_call_resolution_diagnostics(graph_builder)
-        console.print(f"[green]Successfully finished indexing: {path} in {elapsed:.2f} seconds[/green]")
+        _print_index_execution_summary(graph_builder)
+        console.print(f"[green]Successfully finished indexing: {path_obj} in {elapsed:.2f} seconds[/green]")
         
         # Check if auto-watch is enabled
         try:
@@ -363,6 +404,7 @@ def add_package_helper(package_name: str, language: str, context: Optional[str]
     try:
         asyncio.run(_run_index_with_progress(graph_builder, package_path, is_dependency=True, cgcignore_path=ctx.cgcignore_path))
         _print_call_resolution_diagnostics(graph_builder)
+        _print_index_execution_summary(graph_builder)
         console.print(f"[green]Successfully finished indexing package: {package_name}[/green]")
     except Exception as e:
         console.print(f"[bold red]An error occurred during package indexing:[/bold red] {e}")
@@ -415,8 +457,13 @@ def delete_helper(repo_path: str, context: Optional[str] = None):
         else:
             console.print(f"[yellow]Repository not found in graph: {repo_path}[/yellow]")
             console.print("[dim]Tip: Use 'cgc list' to see available repositories.[/dim]")
+            raise typer.Exit(code=1)
+    except typer.Exit:
+        # Control flow, not an error — let it through so the exit code survives.
+        raise
     except Exception as e:
         console.print(f"[bold red]An error occurred:[/bold red] {e}")
+        raise typer.Exit(code=1)
     finally:
         db_manager.close_driver()
 
@@ -480,7 +527,13 @@ def cypher_helper(query: str, context: Optional[str] = None):
         raise typer.Exit(code=1)
 
     backend = getattr(db_manager, "get_backend_type", lambda: "neo4j")()
-    session_kwargs = {"default_access_mode": "READ"} if backend == "neo4j" else {}
+    # Neo4j honours default_access_mode natively; FalkorDB routes READ sessions
+    # through GRAPH.RO_QUERY for server-enforced read-only execution.
+    session_kwargs = (
+        {"default_access_mode": "READ"}
+        if backend in ("neo4j", "falkordb", "falkordb-remote")
+        else {}
+    )
 
     try:
         with db_manager.get_driver().session(**session_kwargs) as session:
@@ -525,8 +578,122 @@ import uvicorn
 import urllib.parse
 from ..viz.server import run_server, set_db_manager
 
+_OFFLINE_VIZ_DEFAULT_QUERY = """
+MATCH (n)-[r]->(m)
+RETURN n, r, m
+LIMIT 300
+"""
+
+
+def _render_offline_visualization(
+    db_manager,
+    repo_path: Optional[str] = None,
+    cypher_query: Optional[str] = None,
+    output_path: Optional[str] = None,
+) -> None:
+    """Render the graph with the dependency-free single-file HTML renderer.
+
+    The React frontend in ``viz/dist`` is not shipped in the wheel, which made
+    every visualization entry point a hard failure on a plain ``pip install``.
+    ``utils/visualize_graph.py`` is a complete, zero-dependency renderer that
+    was sitting in the package with no callers — this wires it up so the
+    command degrades to a working (simpler) view instead of exiting 1.
+    """
+    from ..utils.visualize_graph import open_in_browser, build_graph_data
+
+    query = cypher_query or _OFFLINE_VIZ_DEFAULT_QUERY
+    nodes: Dict[Any, Dict[str, Any]] = {}
+    edges: List[Dict[str, Any]] = []
+
+    def _ident(value) -> Optional[str]:
+        return None if value is None else str(value)
+
+    # Neo4j/Falkor return driver objects carrying .labels / .type; Kùzu and
+    # Ladybug return plain dicts carrying _label plus _src/_dst. Check the
+    # driver attributes first — a driver object may also be dict-like.
+    def _is_relationship(value) -> bool:
+        if hasattr(value, "labels"):
+            return False
+        if hasattr(value, "type"):
+            return True
+        return isinstance(value, dict) and "_src" in value and "_dst" in value
+
+    def _is_node(value) -> bool:
+        if hasattr(value, "labels"):
+            return True
+        if hasattr(value, "type"):
+            return False
+        # Kùzu relationships also carry _label, so _src/_dst is what
+        # distinguishes them from nodes.
+        return isinstance(value, dict) and "_label" in value and "_src" not in value
+
+    def _node_payload(value) -> Dict[str, Any]:
+        if hasattr(value, "labels"):
+            props = dict(value)
+            labels = list(getattr(value, "labels", []) or [])
+            label = labels[0] if labels else "Node"
+            node_id = getattr(value, "element_id", None) or getattr(value, "id", None)
+        else:
+            props, label = dict(value), value.get("_label", "Node")
+            node_id = value.get("_id")
+        if node_id is None:
+            node_id = props.get("path") or props.get("name")
+        return {
+            "id": _ident(node_id),
+            "label": label,
+            "name": props.get("name") or props.get("path") or "",
+            "file_path": props.get("path", ""),
+            "line_number": props.get("line_number"),
+        }
+
+    def _edge_payload(value) -> Optional[Dict[str, Any]]:
+        start = getattr(value, "start_node", None)
+        end = getattr(value, "end_node", None)
+        if start is not None and end is not None:
+            return {
+                "source": _ident(getattr(start, "element_id", None) or getattr(start, "id", None)),
+                "target": _ident(getattr(end, "element_id", None) or getattr(end, "id", None)),
+                "type": getattr(value, "type", "RELATED"),
+            }
+        if isinstance(value, dict):
+            return {
+                "source": _ident(value.get("_src")),
+                "target": _ident(value.get("_dst")),
+                "type": value.get("_label", "RELATED"),
+            }
+        return None
+
+    with db_manager.get_driver().session() as session:
+        for record in session.run(query):
+            values = list(record.values()) if hasattr(record, "values") else list(record)
+            for value in values:
+                if _is_node(value):
+                    payload = _node_payload(value)
+                    if payload["id"] is not None:
+                        nodes[payload["id"]] = payload
+                elif _is_relationship(value):
+                    edge = _edge_payload(value)
+                    if edge and edge["source"] and edge["target"]:
+                        edges.append(edge)
+
+    if not nodes:
+        console.print(
+            "[yellow]No graph data returned — index a repository first "
+            "with 'cgc index <path>'.[/yellow]"
+        )
+        raise typer.Exit(code=1)
+
+    title = f"CGC Code Graph — {Path(repo_path).name}" if repo_path else "CGC Code Graph"
+    graph_data = build_graph_data(list(nodes.values()), edges)
+    path = open_in_browser(graph_data, title=title, output_path=output_path)
+    console.print(
+        f"[green]Rendered {len(nodes)} nodes and {len(edges)} edges to[/green] {path}"
+    )
+
+
 def visualize_helper(
     repo_path: Optional[str] = None,
+    host: str = "127.0.0.1",
     port: int = 8000,
     context: Optional[str] = None,
     cypher_query: Optional[str] = None,
@@ -585,8 +752,15 @@ def visualize_helper(
                     "[dim]then sync[/dim] [cyan]website/dist[/cyan] [dim]→[/dim] "
                     "[cyan]src/codegraphcontext/viz/dist[/cyan][dim].[/dim]"
                 )
-                db_manager.close_driver()
-                raise SystemExit(1)
+                console.print(
+                    "\n[yellow]Falling back to the built-in offline renderer.[/yellow]"
+                )
+                try:
+                    return _render_offline_visualization(
+                        db_manager, repo_path=repo_path, cypher_query=cypher_query
+                    )
+                finally:
+                    db_manager.close_driver()
 
     index_html = static_dir / "index.html"
     if not index_html.is_file():
@@ -621,7 +795,7 @@ def visualize_helper(
     threading.Thread(target=open_browser, daemon=True).start()
     
     try:
-        run_server(host="127.0.0.1", port=port, static_dir=str(static_dir))
+        run_server(host=host, port=port, static_dir=str(static_dir))
     except Exception as e:
         console.print(f"[bold red]An error occurred while running the server:[/bold red] {e}")
         raise typer.Exit(code=1)
@@ -666,6 +840,7 @@ def reindex_helper(path: str, context: Optional[str] = None):
         time_end = time.time()
         elapsed = time_end - time_start
         _print_call_resolution_diagnostics(graph_builder)
+        _print_index_execution_summary(graph_builder)
         console.print(f"[green]Successfully re-indexed: {path} in {elapsed:.2f} seconds[/green]")
     except Exception as e:
         console.print(f"[bold red]An error occurred during re-indexing:[/bold red] {e}")
@@ -774,17 +949,23 @@ def stats_helper(path: str = None, context: Optional[str] = None):
                     return
                 
                 # Get stats
-                # Get stats using separate queries to handle depth and avoid Cartesian products
+                # Get stats using separate queries to handle depth and avoid Cartesian products.
+                # `count(x)` counts *rows*, and a variable-length CONTAINS* match
+                # yields one row per distinct path to the node: a method is
+                # reachable as Repo->..->File->Function and again as
+                # Repo->..->File->Class->Function, a nested function three ways.
+                # count(DISTINCT x) is required or the totals are inflated —
+                # functions were over-reported by ~55% on CGC's own repo.
                 # 1. Files
-                file_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(f:File) RETURN count(f) as c"
+                file_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(f:File) RETURN count(DISTINCT f) as c"
                 file_count = session.run(file_query, path=repo_path_str).single()["c"]
-                
+
                 # 2. Functions (including methods in classes)
-                func_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(func:Function) RETURN count(func) as c"
+                func_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(func:Function) RETURN count(DISTINCT func) as c"
                 func_count = session.run(func_query, path=repo_path_str).single()["c"]
-                
+
                 # 3. Classes
-                class_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(c:Class) RETURN count(c) as c"
+                class_query = "MATCH (r:Repository {path: $path})-[:CONTAINS*]->(c:Class) RETURN count(DISTINCT c) as c"
                 class_count = session.run(class_query, path=repo_path_str).single()["c"]
                 
                 # 4. Modules (imported) - Note: Module nodes are outside the repo structure usually, connected via IMPORTS
@@ -850,7 +1031,12 @@ def stats_helper(path: str = None, context: Optional[str] = None):
         db_manager.close_driver()
 
 
-def watch_helper(path: str, context: Optional[str] = None, use_polling: Optional[bool] = None):
+def watch_helper(
+    path: str,
+    context: Optional[str] = None,
+    use_polling: Optional[bool] = None,
+    sync_on_start: bool = False,
+):
     """Watch a directory for changes and auto-update the graph (blocking mode)."""
     import logging
     from ..core.watcher import CodeWatcher
@@ -913,11 +1099,17 @@ def watch_helper(path: str, context: Optional[str] = None, use_polling: Optional
         
         # Add the directory to watch
         if is_indexed:
-            console.print("[green]✓[/green] Already indexed. Synchronizing current files...")
+            if sync_on_start:
+                console.print("[green]✓[/green] Already indexed. Synchronizing current files...")
+            else:
+                console.print("[green]✓[/green] Already indexed. Watching for future changes only.")
+                console.print(
+                    "[dim]Use 'cgc index --force' or 'cgc watch --sync-on-start' to reconcile existing changes.[/dim]"
+                )
             watcher.watch_directory(
                 str(path_obj),
                 perform_initial_scan=False,
-                sync_on_start=True,
+                sync_on_start=sync_on_start,
                 cgcignore_path=ctx.cgcignore_path,
             )
         else:
@@ -960,24 +1152,43 @@ def watch_helper(path: str, context: Optional[str] = None, use_polling: Optional
     finally:
         watcher.stop()
         db_manager.close_driver()
-        console.print("[green]✓[/green] Watcher stopped. Graph is up to date.")
+        console.print("[green]✓[/green] Watcher stopped.")
 
 
 
 def unwatch_helper(path: str):
-    """Stop watching a directory."""
-    console.print(f"[yellow]⚠️  Note: 'cgc unwatch' only works when the watcher is running via MCP server.[/yellow]")
-    console.print(f"[dim]For CLI watch mode, simply press Ctrl+C in the watch terminal.[/dim]")
-    console.print(f"\n[cyan]Path specified:[/cyan] {Path(path).resolve()}")
+    """Report that unwatching is not available from the CLI.
+
+    This command touches no watcher state at all — it never has. It used to
+    print a note, echo the requested path back as "Path specified:" (which
+    reads like confirmation that something happened, even for a path that was
+    never watched and does not exist) and exit 0.
+    """
+    console.print(
+        "[bold red]Error:[/bold red] 'cgc unwatch' is not supported from the CLI — "
+        "it cannot reach a watcher started in another process."
+    )
+    console.print("[dim]For CLI watch mode, press Ctrl+C in the terminal running 'cgc watch'.[/dim]")
+    console.print(
+        "[dim]For MCP mode, call the 'unwatch_directory' tool from your IDE.[/dim]"
+    )
+    raise typer.Exit(code=1)
 
 
 def list_watching_helper():
-    """List all directories currently being watched."""
-    console.print(f"[yellow]⚠️  Note: 'cgc watching' only works when the watcher is running via MCP server.[/yellow]")
-    console.print(f"[dim]For CLI watch mode, check the terminal where you ran 'cgc watch'.[/dim]")
-    console.print(f"\n[cyan]To see watched directories in MCP mode:[/cyan]")
-    console.print(f"  1. Start the MCP server: cgc mcp start")
-    console.print(f"  2. Use the 'list_watched_paths' MCP tool from your IDE")
+    """Report that listing watched paths is not available from the CLI.
+
+    Same as unwatch: no watcher state is consulted, so exiting 0 advertised a
+    successful listing of nothing.
+    """
+    console.print(
+        "[bold red]Error:[/bold red] 'cgc watching' is not supported from the CLI — "
+        "it cannot reach a watcher started in another process."
+    )
+    console.print("[dim]For CLI watch mode, check the terminal where you ran 'cgc watch'.[/dim]")
+    console.print("[dim]For MCP mode: start 'cgc mcp start', then call the "
+                  "'list_watched_paths' tool from your IDE.[/dim]")
+    raise typer.Exit(code=1)
 
 
 def setup_scip_helper() -> None: