codegraph-engine 2.1.7__py3-none-any.whl → 2.2.0__py3-none-any.whl

codegraph/__init__.py

@@ -1,6 +1,6 @@
 """CodeGraph MCP: local, evidence-backed codebase intelligence."""
 
-__version__ = "2.1.7"
+__version__ = "2.2.0"
 from codegraph.errors import (
     CodeGraphError,
     ErrorCode,

codegraph/cli.py

@@ -9,6 +9,7 @@ import typer
 
 from codegraph import __version__
 from codegraph.architecture import get_architecture
+from codegraph.cli_output import cli_echo
 from codegraph.config import Settings
 from codegraph.context import get_context
 from codegraph.errors import ErrorCode, SecurityError
@@ -433,6 +434,8 @@ def routes(
     framework: Annotated[str | None, typer.Option("--framework", "-f", help="Filter by framework (e.g. flask, fastapi)")] = None,
     method: Annotated[str | None, typer.Option("--method", "-m", help="Filter by HTTP method (e.g. GET, POST)")] = None,
     route_path: Annotated[str | None, typer.Option("--path", "-p", help="Filter by route path substring")] = None,
+    limit: Annotated[int | None, typer.Option("--limit", "-l", help="Maximum number of routes to return")] = None,
+    offset: Annotated[int, typer.Option("--offset", help="Number of routes to skip")] = 0,
     json_output: Annotated[bool, typer.Option("--json", help="Output raw JSON array")] = False,
 ) -> None:
     """List and inspect indexed framework routes."""
@@ -478,6 +481,11 @@ def routes(
             for r in rows
         ]
 
+        if limit is not None:
+            safe_offset = max(0, offset)
+            safe_limit = max(0, limit)
+            route_list = route_list[safe_offset : safe_offset + safe_limit]
+
         if json_output:
             typer.echo(json.dumps(route_list, indent=2))
         else:
@@ -596,17 +604,60 @@ def debug(
         )
 
 
+@app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run_cmd(
+    ctx: typer.Context,
+    command: Annotated[list[str] | None, typer.Argument(help="Development command and arguments to execute")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    sample_rate: Annotated[float, typer.Option("--sample-rate", help="Sampling rate for trace capture (0.0..1.0)")] = 1.0,
+) -> None:
+    """Execute a development command or server with transparent runtime trace capture."""
+    full_cmd = (command or []) + ctx.args
+    if not full_cmd:
+        cli_echo("Error: Command cannot be empty. Usage: codegraph run <command> [args...]")
+        raise typer.Exit(code=1)
+
+    repo = _resolve_repo(None, repository)
+    from codegraph.runtime.runner import run_with_telemetry
+
+    exit_code = run_with_telemetry(full_cmd, repository=repo, sample_rate=sample_rate)
+    raise typer.Exit(code=exit_code)
+
+
+def _run_server(
+    path: Path | None,
+    repository: Path | None,
+    profile: str,
+    transport: str = "stdio",
+    host: str = "127.0.0.1",
+    port: int = 8765,
+) -> None:
+    repo = _resolve_repo(path, repository)
+    from codegraph.mcp import create_server
+    from codegraph.process_lifecycle import run_mcp_stdio_server
+
+    if transport.lower() == "sse":
+        server = create_server(repo, profile=profile, host=host, port=port)
+        server.run(transport="sse")
+    else:
+        server = create_server(repo, profile=profile)
+        run_mcp_stdio_server(server, repo, profile=profile)
+
+
 @app.command()
 def serve(
     path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
     repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
     profile: Annotated[str, typer.Option("--profile", help="Tool profile: core | minimal | developer | full")] = "full",
+    transport: Annotated[str, typer.Option("--transport", "-t", help="MCP transport: stdio | sse")] = "stdio",
+    host: Annotated[str, typer.Option("--host", help="Host for SSE server")] = "127.0.0.1",
+    port: Annotated[int, typer.Option("--port", "-p", help="Port for SSE server")] = 8765,
 ) -> None:
-    """Run the stdio MCP server (requires the optional mcp extra)."""
-    repo = _resolve_repo(path, repository)
-    from codegraph.mcp import create_server
-
-    create_server(repo, profile=profile).run()
+    """Run the CodeGraph MCP server via stdio or SSE transport."""
+    _run_server(path, repository, profile, transport=transport, host=host, port=port)
 
 
 mcp_app = typer.Typer(help="MCP server commands.")
@@ -618,12 +669,72 @@ def mcp_serve(
     path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
     repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
     profile: Annotated[str, typer.Option("--profile", help="Tool profile: core | graph | minimal | developer | full")] = "full",
+    transport: Annotated[str, typer.Option("--transport", "-t", help="MCP transport: stdio | sse")] = "stdio",
+    host: Annotated[str, typer.Option("--host", help="Host for SSE server")] = "127.0.0.1",
+    port: Annotated[int, typer.Option("--port", "-p", help="Port for SSE server")] = 8765,
 ) -> None:
-    """Run the stdio MCP server (requires the optional mcp extra)."""
-    repo = _resolve_repo(path, repository)
-    from codegraph.mcp import create_server
+    """Run the CodeGraph MCP server via stdio or SSE transport."""
+    _run_server(path, repository, profile, transport=transport, host=host, port=port)
 
-    create_server(repo, profile=profile).run()
+
+def _execute_stop(
+    path: Path | None,
+    repository: Path | None,
+    all_processes: bool,
+    timeout: float,
+    json_output: bool,
+) -> None:
+    from codegraph.process_lifecycle import stop_codegraph_processes
+
+    target_repo: Path | None = None
+    if not all_processes:
+        target_repo = _resolve_repo(path, repository)
+
+    res = stop_codegraph_processes(
+        repository=target_repo,
+        stop_all=all_processes,
+        timeout_sec=timeout,
+    )
+    if json_output:
+        cli_echo(json.dumps(res.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(res.format_human())
+
+
+@app.command("stop")
+def stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("stop")
+def mcp_stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("kill")
+def mcp_kill_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 1.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Alias for `codegraph stop` to terminate CodeGraph MCP processes and release locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
 
 
 @mcp_app.command("doctor")
@@ -636,9 +747,9 @@ def mcp_doctor(
 
     report = run_mcp_doctor(profile=profile)
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
     if not report.healthy:
         raise typer.Exit(code=1)
 
@@ -656,9 +767,9 @@ def mcp_config_check(
     ws = (path or Path.cwd()).resolve()
     rep = check_mcp_configuration(workspace_dir=ws, config_file=config_file, include_example=include_example)
     if json_output:
-        typer.echo(json.dumps(rep.as_dict(), indent=2))
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(f"{rep.status.value}: {rep.message}")
+        cli_echo(f"{rep.status.value}: {rep.message}")
 
 
 @mcp_app.command("capabilities")
@@ -666,7 +777,7 @@ def mcp_capabilities() -> None:
     """Output the deterministic machine-readable CodeGraph capability manifest."""
     from codegraph.agent_capabilities import get_capability_manifest
 
-    typer.echo(json.dumps(get_capability_manifest(), indent=2))
+    cli_echo(json.dumps(get_capability_manifest(), indent=2), json_mode=True)
 
 
 @mcp_app.command("rules")
@@ -676,7 +787,7 @@ def mcp_rules(
     """Render deterministic CodeGraph agent rules for the specified agent."""
     from codegraph.agent_rules import render_agent_rules
 
-    typer.echo(render_agent_rules(agent=agent), nl=False)
+    cli_echo(render_agent_rules(agent=agent), nl=False)
 
 
 @app.command()
@@ -685,9 +796,20 @@ def doctor(
     repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
     resources: Annotated[bool, typer.Option("--resources")] = False,
     database: Annotated[bool, typer.Option("--database", help="Run comprehensive database integrity and schema checks")] = False,
+    processes: Annotated[bool, typer.Option("--processes", help="Inspect active CodeGraph processes, parent state, and stale PID files")] = False,
     json_output: Annotated[bool, typer.Option("--json")] = False,
 ) -> None:
-    """Check repository and index readiness, database integrity, and freshness."""
+    """Check repository and index readiness, database integrity, process lifecycle, and freshness."""
+    if processes:
+        from codegraph.process_lifecycle import discover_codegraph_processes
+
+        discovery = discover_codegraph_processes(clean_stale=True)
+        if json_output:
+            cli_echo(json.dumps(discovery.as_dict(), indent=2), json_mode=True)
+        else:
+            cli_echo(discovery.format_human())
+        return
+
     repo = _resolve_repo(path, repository)
     indexer_inst = _indexer(repo)
     db = repo / ".codegraph.sqlite3"
@@ -1007,7 +1129,7 @@ def install(
 
             rules_txt = render_agent_rules(canon)
             if json_output:
-                typer.echo(
+                cli_echo(
                     json.dumps(
                         {
                             "status": "ok",
@@ -1016,21 +1138,22 @@ def install(
                             "instructions_block": format_marker_block(rules_txt),
                         },
                         indent=2,
-                    )
+                    ),
+                    json_mode=True,
                 )
             else:
-                typer.echo(f"# MCP Configuration ({canon})\n")
-                typer.echo(json.dumps(snippet, indent=2))
-                typer.echo(f"\n# Instructions Block ({canon})\n")
-                typer.echo(format_marker_block(rules_txt), nl=False)
+                cli_echo(f"# MCP Configuration ({canon})\n")
+                cli_echo(json.dumps(snippet, indent=2), json_mode=True)
+                cli_echo(f"\n# Instructions Block ({canon})\n")
+                cli_echo(format_marker_block(rules_txt), nl=False)
             return
         except CodeGraphError as exc:
             if json_output:
-                typer.echo(json.dumps(exc.to_response(), indent=2))
+                cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
             else:
-                typer.echo(f"Error [{exc.code}]: {exc.message}")
+                cli_echo(f"Error [{exc.code}]: {exc.message}")
                 if exc.next_action and exc.next_action.get("command"):
-                    typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                    cli_echo(f"\nTry:\n  {exc.next_action['command']}")
             raise typer.Exit(code=1) from exc
 
     ws = _resolve_repo(path, repository)
@@ -1040,15 +1163,15 @@ def install(
 
         assert isinstance(preview_rep, InstallerReport)
         if not json_output:
-            typer.echo(preview_rep.format_preview_human())
-            typer.echo("")
-            typer.echo("Continue? [y/N] ", nl=False)
+            cli_echo(preview_rep.format_preview_human())
+            cli_echo("")
+            cli_echo("Continue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1062,22 +1185,22 @@ def install(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("reason"):
-                typer.echo(f"\nExpected:\n  {exc.next_action['reason']}")
+                cli_echo(f"\nExpected:\n  {exc.next_action['reason']}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
         if yes and not dry_run:
-            typer.echo(report.format_preview_human())
-            typer.echo("")
-        typer.echo(report.format_human())
+            cli_echo(report.format_preview_human())
+            cli_echo("")
+        cli_echo(report.format_human())
 
     if report.status == "error":
         raise typer.Exit(code=1)
@@ -1107,17 +1230,17 @@ def uninstall(
 
     def _confirm_uninstall(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("CodeGraph Uninstaller\n")
+            cli_echo("CodeGraph Uninstaller\n")
             for c in preview_rep.changes:
                 if c.action in ("remove", "modify"):
-                    typer.echo(f"  - {c.display_path} ({c.action})")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                    cli_echo(f"  - {c.display_path} ({c.action})")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1130,17 +1253,17 @@ def uninstall(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 @app.command()
@@ -1159,16 +1282,16 @@ def uninit(
 
     def _confirm_uninit(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("Remove CodeGraph project index files?\n")
+            cli_echo("Remove CodeGraph project index files?\n")
             for c in preview_rep.changes:
-                typer.echo(f"  - {c.display_path}")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                cli_echo(f"  - {c.display_path}")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1179,15 +1302,15 @@ def uninit(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 if __name__ == "__main__":

codegraph/cli_output.py

@@ -0,0 +1,190 @@
+"""Centralized cross-platform CLI output utility for Windows/macOS/Linux encoding safety.
+
+Guarantees:
+- Never assumes stdout/stderr is UTF-8 (safe on Windows cp1252, cp437, ASCII, and redirected pipes).
+- Preserves rich Unicode symbols (`✓`, `✗`, `⚠`, `↻`, `(•)`) when the target stream supports them.
+- Automatically degrades to deterministic ASCII markers (`[OK]`, `[ERROR]`, `[WARN]`, `[REPAIRED]`, `(*)`)
+  when the stream encoding does not support Unicode box/status glyphs.
+- Ensures `--json` output is strictly machine-readable and never contains decorative Unicode glyphs.
+"""
+from __future__ import annotations
+
+import codecs
+import os
+import sys
+from dataclasses import dataclass
+from typing import Any, TextIO
+
+import typer
+
+_PROBE_GLYPHS = "✓✗⚠↻•→↓─—–"
+
+# Ordered replacements so multi-char patterns (e.g. "(•)") are replaced before single chars ("•")
+_UNICODE_TO_ASCII_MAP: tuple[tuple[str, str], ...] = (
+    ("(•)", "(*)"),
+    ("✓", "[OK]"),
+    ("✗", "[ERROR]"),
+    ("⚠", "[WARN]"),
+    ("↻", "[REPAIRED]"),
+    ("•", "*"),
+    ("→", "->"),
+    ("↓", "v"),
+    ("—", "--"),
+    ("–", "-"),
+    ("─", "-"),
+)
+
+
+@dataclass(frozen=True)
+class CliSymbols:
+    """Encoding-aware CLI status symbols."""
+
+    unicode_enabled: bool
+    ok: str
+    error: str
+    warn: str
+    repair: str
+    radio_on: str
+    radio_off: str
+    arrow_right: str
+    arrow_down: str
+
+
+UNICODE_SYMBOLS = CliSymbols(
+    unicode_enabled=True,
+    ok="✓",
+    error="✗",
+    warn="⚠",
+    repair="↻",
+    radio_on="(•)",
+    radio_off="( )",
+    arrow_right="→",
+    arrow_down="↓",
+)
+
+ASCII_SYMBOLS = CliSymbols(
+    unicode_enabled=False,
+    ok="[OK]",
+    error="[ERROR]",
+    warn="[WARN]",
+    repair="[REPAIRED]",
+    radio_on="(*)",
+    radio_off="( )",
+    arrow_right="->",
+    arrow_down="v",
+)
+
+
+def detect_stream_encoding(stream: Any = None) -> str:
+    """Safely detect the character encoding of `stream` (defaults to `sys.stdout`)."""
+    target = stream if stream is not None else sys.stdout
+    enc = getattr(target, "encoding", None)
+    if not enc or not isinstance(enc, str):
+        return "ascii"
+    try:
+        info = codecs.lookup(enc)
+        return info.name
+    except LookupError:
+        return "ascii"
+
+
+def supports_unicode(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> bool:
+    """Return True if `stream` can encode all CodeGraph Unicode status glyphs without error."""
+    if unicode_override is not None:
+        return unicode_override
+
+    env_ascii = os.environ.get("CODEGRAPH_ASCII_OUTPUT", "").strip().lower()
+    if env_ascii in ("1", "true", "yes", "on"):
+        return False
+
+    env_unicode = os.environ.get("CODEGRAPH_UNICODE_OUTPUT", "").strip().lower()
+    if env_unicode in ("1", "true", "yes", "on"):
+        return True
+    if env_unicode in ("0", "false", "no", "off"):
+        return False
+
+    enc = detect_stream_encoding(stream)
+    try:
+        _PROBE_GLYPHS.encode(enc, errors="strict")
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def get_cli_symbols(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> CliSymbols:
+    """Return `UNICODE_SYMBOLS` when supported by `stream`, else `ASCII_SYMBOLS`."""
+    if supports_unicode(stream, unicode_override=unicode_override):
+        return UNICODE_SYMBOLS
+    return ASCII_SYMBOLS
+
+
+def sanitize_text_for_stream(
+    text: str,
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> str:
+    """Format `text` safely for `stream`, converting decorative Unicode when unsupported."""
+    if not text:
+        return text
+
+    target = stream if stream is not None else sys.stdout
+    use_unicode = supports_unicode(target, unicode_override=unicode_override)
+    out = text
+    if not use_unicode:
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+
+    enc = detect_stream_encoding(target)
+    try:
+        out.encode(enc, errors="strict")
+        return out
+    except (UnicodeEncodeError, LookupError):
+        # Replace any remaining unencodable glyphs cleanly so write() never raises UnicodeEncodeError
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+        return out.encode(enc, errors="replace").decode(enc, errors="replace")
+
+
+def sanitize_json_string(raw_json: str, stream: Any = None) -> str:
+    """Ensure machine-readable JSON output never crashes non-UTF-8 streams."""
+    enc = detect_stream_encoding(stream)
+    try:
+        raw_json.encode(enc, errors="strict")
+        return raw_json
+    except (UnicodeEncodeError, LookupError):
+        # Escape non-ASCII characters using standard JSON \uXXXX escapes
+        return raw_json.encode("unicode_escape").decode("ascii")
+
+
+def cli_echo(
+    message: str = "",
+    *,
+    nl: bool = True,
+    err: bool = False,
+    json_mode: bool = False,
+    stream: TextIO | None = None,
+    unicode_override: bool | None = None,
+) -> None:
+    """Centralized safe CLI output function replacing raw `typer.echo`."""
+    target = stream if stream is not None else (sys.stderr if err else sys.stdout)
+    if json_mode:
+        safe_msg = sanitize_json_string(str(message), target)
+    else:
+        safe_msg = sanitize_text_for_stream(str(message), target, unicode_override=unicode_override)
+
+    if stream is not None:
+        stream.write(safe_msg + ("\n" if nl else ""))
+        stream.flush()
+    else:
+        typer.echo(safe_msg, nl=nl, err=err)