cli-web-hackernews 0.1.0__py3-none-any.whl

cli_web/hackernews/utils/doctor.py

@@ -0,0 +1,188 @@
+"""``doctor`` — self-diagnosis for cli-web-* CLIs.
+
+CANONICAL SOURCE: cli-web-core/cli_web_core/doctor.py
+Vendored into every generated CLI at cli_web/<app>/utils/doctor.py by
+`cli-web-devkit resync`. Do not edit vendored copies by hand.
+
+Checks the local environment a support thread would ask about first:
+installation, Python version, config directory, auth material (when the
+CLI has an auth module), and optional dependencies. Read-only — never
+mutates state, never touches the network.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import stat
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class DoctorCheck:
+    name: str
+    status: str  # "ok" | "warn" | "fail"
+    detail: str = ""
+
+
+def _check_entry_point(app_name: str) -> DoctorCheck:
+    binary = f"cli-web-{app_name}"
+    path = shutil.which(binary)
+    if path:
+        return DoctorCheck("entry point", "ok", path)
+    return DoctorCheck(
+        "entry point",
+        "warn",
+        f"{binary} not on PATH — run `pip install -e .` in agent-harness/ "
+        f"(python -m fallback still works)",
+    )
+
+
+def _check_python() -> DoctorCheck:
+    # Intentional runtime guard: direct-source runs bypass pip's
+    # python_requires, so the interpreter check must live here.
+    if sys.version_info >= (3, 10):  # noqa: UP036
+        return DoctorCheck("python", "ok", sys.version.split()[0])
+    return DoctorCheck("python", "fail", f"{sys.version.split()[0]} < 3.10 (unsupported)")
+
+
+def _config_dir(app_name: str) -> Path:
+    return Path.home() / ".config" / f"cli-web-{app_name}"
+
+
+def _check_config_dir(app_name: str) -> DoctorCheck:
+    cfg = _config_dir(app_name)
+    if not cfg.exists():
+        return DoctorCheck("config dir", "ok", f"{cfg} (not created yet — created on first use)")
+    if os.access(cfg, os.W_OK):
+        return DoctorCheck("config dir", "ok", str(cfg))
+    return DoctorCheck("config dir", "fail", f"{cfg} is not writable")
+
+
+def _has_auth_module(pkg: str) -> bool:
+    try:
+        return importlib.util.find_spec(f"cli_web.{pkg}.core.auth") is not None
+    except (ImportError, ModuleNotFoundError, ValueError):
+        return False
+
+
+def _check_auth(app_name: str, pkg: str) -> list[DoctorCheck]:
+    if not _has_auth_module(pkg):
+        return [DoctorCheck("auth", "ok", "no auth module — public site, nothing to configure")]
+
+    checks: list[DoctorCheck] = []
+    if importlib.util.find_spec("playwright") is None:
+        checks.append(
+            DoctorCheck(
+                "playwright",
+                "warn",
+                "not installed — `auth login` (browser flow) unavailable; "
+                "pip install playwright && playwright install chromium",
+            )
+        )
+    else:
+        checks.append(DoctorCheck("playwright", "ok", "installed"))
+
+    env_var = f"CLI_WEB_{app_name.upper().replace('-', '_')}_AUTH_JSON"
+    if os.environ.get(env_var):
+        checks.append(DoctorCheck("auth source", "ok", f"using env var {env_var}"))
+        return checks
+
+    auth_file = _config_dir(app_name) / "auth.json"
+    if not auth_file.is_file():
+        checks.append(
+            DoctorCheck(
+                "auth file",
+                "warn",
+                f"{auth_file} missing — run: cli-web-{app_name} auth login (or set {env_var})",
+            )
+        )
+        return checks
+
+    checks.append(DoctorCheck("auth file", "ok", str(auth_file)))
+    if os.name == "posix":  # st_mode permission bits are meaningless on Windows
+        mode = stat.S_IMODE(auth_file.stat().st_mode)
+        if mode & 0o077:
+            checks.append(
+                DoctorCheck(
+                    "auth file permissions",
+                    "warn",
+                    f"{oct(mode)} — should be 600; run: chmod 600 {auth_file}",
+                )
+            )
+        else:
+            checks.append(DoctorCheck("auth file permissions", "ok", oct(mode)))
+    try:
+        json.loads(auth_file.read_text(encoding="utf-8"))
+        checks.append(DoctorCheck("auth file format", "ok", "valid JSON"))
+    except (OSError, json.JSONDecodeError) as exc:
+        checks.append(DoctorCheck("auth file format", "fail", f"unreadable: {exc}"))
+
+    return checks
+
+
+def _check_optional_deps() -> list[DoctorCheck]:
+    checks = []
+    if importlib.util.find_spec("prompt_toolkit") is None:
+        checks.append(
+            DoctorCheck("prompt_toolkit", "ok", "not installed — REPL uses plain input()")
+        )
+    else:
+        checks.append(DoctorCheck("prompt_toolkit", "ok", "installed (REPL autocomplete on)"))
+    return checks
+
+
+def run_doctor(app_name: str, pkg: str) -> list[DoctorCheck]:
+    checks = [
+        _check_python(),
+        _check_entry_point(app_name),
+        _check_config_dir(app_name),
+        *_check_auth(app_name, pkg),
+        *_check_optional_deps(),
+    ]
+    return checks
+
+
+def register_doctor_command(cli: Any, app_name: str, pkg: str | None = None) -> None:
+    """Attach a ``doctor`` command to a cli-web-* Click group."""
+    import click
+
+    resolved_pkg = pkg or app_name.replace("-", "_")
+
+    @cli.command("doctor")
+    @click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+    @click.pass_context
+    def doctor(ctx: Any, json_mode: bool) -> None:
+        """Diagnose this CLI's local setup (install, auth, dependencies)."""
+        if not json_mode:  # honor the group-level --json flag (ctx.obj["json"])
+            obj = ctx.find_root().obj
+            json_mode = bool(obj.get("json")) if isinstance(obj, dict) else False
+        checks = run_doctor(app_name, resolved_pkg)
+        failed = [c for c in checks if c.status == "fail"]
+        if json_mode:
+            click.echo(
+                json.dumps(
+                    {
+                        "success": not failed,
+                        "data": {
+                            "checks": [asdict(c) for c in checks],
+                            "ok": not failed,
+                        },
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            marks = {"ok": "✓", "warn": "⚠", "fail": "✗"}
+            for c in checks:
+                detail = f"  {c.detail}" if c.detail else ""
+                click.echo(f" {marks[c.status]} {c.name}:{detail}")
+            click.echo()
+            click.echo("all good" if not failed else f"{len(failed)} problem(s) found")
+        if failed:
+            raise SystemExit(1)

cli_web/hackernews/utils/helpers.py

@@ -0,0 +1,73 @@
+"""Shared helpers for cli-web-hackernews."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import sys
+
+import click
+from cli_web.hackernews.core.exceptions import AppError
+
+
+@contextlib.contextmanager
+def handle_errors(json_mode: bool = False):
+    """Context manager for consistent error handling in commands."""
+    try:
+        yield
+    except AppError as exc:
+        if json_mode:
+            click.echo(json.dumps(exc.to_dict()), err=False)
+        else:
+            click.echo(f"Error: {exc.message}", err=True)
+        sys.exit(1)
+    except Exception as exc:
+        if json_mode:
+            click.echo(
+                json.dumps(
+                    {
+                        "error": True,
+                        "code": "UNEXPECTED_ERROR",
+                        "message": str(exc),
+                    }
+                ),
+                err=False,
+            )
+        else:
+            click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+def resolve_json_mode(use_json: bool) -> bool:
+    """Resolve --json flag, checking parent context too."""
+    if use_json:
+        return True
+    ctx = click.get_current_context(silent=True)
+    if ctx and ctx.obj:
+        return ctx.obj.get("json", False)
+    return False
+
+
+def print_json(data) -> None:
+    """Print data as formatted JSON."""
+    click.echo(json.dumps(data, indent=2, default=str))
+
+
+def _resolve_cli(name: str) -> str:
+    """Find the CLI binary path for subprocess tests."""
+    # Check if forced to use installed version
+    if os.environ.get("CLI_WEB_FORCE_INSTALLED"):
+        path = shutil.which(name)
+        if path:
+            return path
+        raise FileNotFoundError(f"{name} not found in PATH")
+
+    # Try which first
+    path = shutil.which(name)
+    if path:
+        return path
+
+    # Fallback to python -m
+    return f"{sys.executable} -m cli_web.hackernews"

cli_web/hackernews/utils/mcp_server.py

@@ -0,0 +1,290 @@
+"""MCP server adapter — expose a cli-web-* Click CLI as MCP tools.
+
+CANONICAL SOURCE: cli-web-core/cli_web_core/mcp_server.py
+Vendored into every generated CLI at cli_web/<app>/utils/mcp_server.py by
+`cli-web-devkit resync`. Do not edit vendored copies by hand.
+
+Every cli-web-* command already speaks ``--json``, so the Click command
+tree maps 1:1 onto MCP tools: tool names are ``group_subcommand``, input
+schemas are derived from Click parameters, and each ``tools/call`` spawns
+the CLI as a fresh subprocess with ``--json`` forced, returning the JSON
+envelope as the tool result. Spawning per call (rather than running
+in-process) gives every tool the same clean-process isolation as a normal
+CLI invocation — no auth/session/global state leaks between calls, and a
+wedged command cannot hang the server. Transport: MCP stdio
+(newline-delimited JSON-RPC 2.0).
+
+Usage (wired automatically into generated CLIs)::
+
+    cli-web-<app> mcp-serve
+
+Then point any MCP client at that command.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from typing import Any
+
+PROTOCOL_VERSION = "2024-11-05"
+
+_CLICK_TYPE_MAP = {
+    "integer": "integer",
+    "int": "integer",
+    "float": "number",
+    "boolean": "boolean",
+    "bool": "boolean",
+}
+
+
+def _is_multi_valued(param: Any) -> bool:
+    return bool(getattr(param, "multiple", False)) or getattr(param, "nargs", 1) != 1
+
+
+def _param_schema(param: Any) -> dict[str, Any]:
+    type_name = getattr(param.type, "name", "text") or "text"
+    json_type = _CLICK_TYPE_MAP.get(type_name.lower(), "string")
+    schema: dict[str, Any] = {"type": json_type}
+    choices = getattr(param.type, "choices", None)
+    if choices:
+        schema["enum"] = list(choices)
+    if _is_multi_valued(param):
+        schema = {"type": "array", "items": schema}
+    help_text = getattr(param, "help", None)
+    if help_text:
+        schema["description"] = help_text
+    return schema
+
+
+def _iter_leaf_commands(
+    group: Any, prefix: tuple[str, ...] = ()
+) -> list[tuple[tuple[str, ...], Any]]:
+    """Flatten a Click group into (path, command) leaves."""
+    import click
+
+    leaves: list[tuple[tuple[str, ...], Any]] = []
+    for name in sorted(group.commands):
+        cmd = group.commands[name]
+        if getattr(cmd, "hidden", False) or name == "mcp-serve":
+            continue
+        path = (*prefix, name)
+        if isinstance(cmd, click.Group):
+            leaves.extend(_iter_leaf_commands(cmd, path))
+        else:
+            leaves.append((path, cmd))
+    return leaves
+
+
+def _is_json_flag(param: Any) -> bool:
+    return "--json" in getattr(param, "opts", ()) or param.name in ("json_mode", "as_json")
+
+
+def _tool_for(path: tuple[str, ...], cmd: Any) -> dict[str, Any]:
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for param in cmd.params:
+        if _is_json_flag(param) or param.name == "help":
+            continue
+        properties[param.name] = _param_schema(param)
+        if getattr(param, "required", False):
+            required.append(param.name)
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return {
+        "name": "_".join(path).replace("-", "_"),
+        "description": (cmd.help or cmd.short_help or " ".join(path)).strip(),
+        "inputSchema": schema,
+    }
+
+
+def _build_argv(
+    path: tuple[str, ...], cmd: Any, arguments: dict[str, Any], json_flag: bool
+) -> list[str]:
+    """Translate MCP tool arguments back into a Click argv."""
+    import click
+
+    argv = list(path)
+    for param in cmd.params:
+        if _is_json_flag(param) or param.name not in arguments:
+            continue
+        value = arguments[param.name]
+        if value is None:
+            continue
+        values = list(value) if isinstance(value, (list, tuple)) else [value]
+        if isinstance(param, click.Argument):
+            argv.extend(str(v) for v in values)
+        elif getattr(param, "is_flag", False):
+            if value:
+                argv.append(param.opts[0])
+        elif _is_multi_valued(param):
+            for v in values:
+                argv.extend([param.opts[0], str(v)])
+        else:
+            argv.extend([param.opts[0], str(value)])
+    if json_flag:
+        argv.append("--json")
+    return argv
+
+
+def _cmd_supports_json(cmd: Any) -> bool:
+    return any(_is_json_flag(p) for p in cmd.params)
+
+
+class McpServer:
+    def __init__(
+        self,
+        cli: Any,
+        app_name: str,
+        version: str = "0.1.0",
+        pkg: str | None = None,
+        *,
+        timeout: float = 300.0,
+        executor: Callable[[list[str]], tuple[str, bool]] | None = None,
+    ):
+        self.cli = cli
+        self.app_name = app_name
+        self.version = version
+        #: Namespace sub-package, for the ``python -m`` subprocess fallback.
+        self.pkg = pkg or app_name.replace("-", "_")
+        #: Per-call subprocess timeout (seconds).
+        self.timeout = timeout
+        #: Optional ``(argv) -> (text, is_error)`` override. Defaults to a
+        #: fresh subprocess per call; injected in tests to run an in-memory
+        #: Click group without an installed binary.
+        self._executor = executor
+        self._leaves: dict[str, tuple[tuple[str, ...], Any]] = {}
+        for path, cmd in _iter_leaf_commands(cli):
+            tool_name = "_".join(path).replace("-", "_")
+            self._leaves[tool_name] = (path, cmd)
+
+    # ── JSON-RPC handlers ────────────────────────────────────────────
+
+    def handle(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        method = message.get("method", "")
+        msg_id = message.get("id")
+        if method == "initialize":
+            return self._result(
+                msg_id,
+                {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {
+                        "name": f"cli-web-{self.app_name}",
+                        "version": self.version,
+                    },
+                },
+            )
+        if method.startswith("notifications/"):
+            return None
+        if method == "tools/list":
+            tools = [_tool_for(path, cmd) for path, cmd in self._leaves.values()]
+            return self._result(msg_id, {"tools": tools})
+        if method == "tools/call":
+            return self._call_tool(msg_id, message.get("params") or {})
+        if method == "ping":
+            return self._result(msg_id, {})
+        return self._error(msg_id, -32601, f"Method not found: {method}")
+
+    def _call_tool(self, msg_id: Any, params: dict[str, Any]) -> dict[str, Any]:
+        name = params.get("name", "")
+        if name not in self._leaves:
+            return self._error(msg_id, -32602, f"Unknown tool: {name}")
+        path, cmd = self._leaves[name]
+        arguments = params.get("arguments") or {}
+        argv = _build_argv(path, cmd, arguments, json_flag=_cmd_supports_json(cmd))
+
+        executor = self._executor or self._subprocess_execute
+        text, is_error = executor(argv)
+        return self._result(
+            msg_id,
+            {
+                "content": [{"type": "text", "text": text}],
+                "isError": is_error,
+            },
+        )
+
+    # ── command execution ────────────────────────────────────────────
+
+    def _base_command(self) -> list[str]:
+        """Resolve how to invoke this CLI as a subprocess.
+
+        Prefer the installed console script; fall back to ``python -m`` so the
+        server still works from a source checkout without ``pip install``.
+        """
+        import shutil
+
+        binary = shutil.which(f"cli-web-{self.app_name}")
+        if binary:
+            return [binary]
+        return [sys.executable, "-m", f"cli_web.{self.pkg}"]
+
+    def _subprocess_execute(self, argv: list[str]) -> tuple[str, bool]:
+        """Run one tool call as a fresh subprocess — full process isolation.
+
+        Each call is a clean process, identical to how a user (and the test
+        suite) invokes the CLI, so no auth/session/global state leaks between
+        calls and a stuck command cannot wedge the server.
+        """
+        import subprocess
+
+        command = [*self._base_command(), *argv]
+        try:
+            proc = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return (f"command timed out after {self.timeout}s", True)
+        except (FileNotFoundError, OSError) as exc:
+            return (f"failed to run cli-web-{self.app_name}: {exc}", True)
+        # The --json success and error envelopes both go to stdout; fall back
+        # to stderr for hard failures (e.g. a Click usage error, exit 2).
+        text = proc.stdout.strip() or proc.stderr.strip()
+        return (text, proc.returncode != 0)
+
+    @staticmethod
+    def _result(msg_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": msg_id, "result": result}
+
+    @staticmethod
+    def _error(msg_id: Any, code: int, message: str) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}}
+
+    # ── stdio loop ───────────────────────────────────────────────────
+
+    def serve_stdio(self) -> None:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                print(
+                    json.dumps(self._error(None, -32700, "Parse error")),
+                    flush=True,
+                )
+                continue
+            response = self.handle(message)
+            if response is not None:
+                print(json.dumps(response), flush=True)
+
+
+def register_mcp_command(
+    cli: Any, app_name: str, version: str = "0.1.0", pkg: str | None = None
+) -> None:
+    """Attach an ``mcp-serve`` command to a cli-web-* Click group."""
+    import click
+
+    @cli.command("mcp-serve", hidden=False)
+    def mcp_serve() -> None:
+        """Serve this CLI as an MCP server over stdio (newline JSON-RPC)."""
+        McpServer(cli, app_name=app_name, version=version, pkg=pkg).serve_stdio()
+
+    _ = click  # imported for parity with vendored runtime deps

cli_web/hackernews/utils/output.py

@@ -0,0 +1,136 @@
+"""Output formatting for cli-web-hackernews (JSON and human-readable tables)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def _safe(text: str, width: int = 0) -> str:
+    """Truncate text to width and replace un-encodable characters."""
+    if width:
+        text = text[:width]
+    encoding = getattr(sys.stdout, "encoding", "utf-8") or "utf-8"
+    return text.encode(encoding, errors="replace").decode(encoding)
+
+
+def print_json(data: Any) -> None:
+    """Print data as formatted JSON to stdout."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def print_error_json(error: Exception) -> None:
+    """Print an error as JSON."""
+    from cli_web.hackernews.core.exceptions import AppError
+
+    if isinstance(error, AppError):
+        print_json(error.to_dict())
+    else:
+        print_json({"error": True, "code": "UNKNOWN_ERROR", "message": str(error)})
+
+
+def print_stories_table(stories: list) -> None:
+    """Print stories as a human-readable table."""
+    if not stories:
+        print("No stories found.")
+        return
+
+    col_rank = 4
+    col_title = 55
+    col_score = 6
+    col_by = 14
+    col_comments = 8
+    col_age = 8
+
+    header = (
+        f"{'#':<{col_rank}} "
+        f"{'Title':<{col_title}} "
+        f"{'Pts':>{col_score}} "
+        f"{'By':<{col_by}} "
+        f"{'Cmts':>{col_comments}} "
+        f"{'Age':>{col_age}}"
+    )
+    print(header)
+    print("-" * len(header))
+
+    for i, story in enumerate(stories, start=1):
+        title = _safe(story.title, col_title)
+        by = _safe(story.by, col_by)
+        print(
+            f"{i:<{col_rank}} "
+            f"{title:<{col_title}} "
+            f"{story.score:>{col_score}} "
+            f"{by:<{col_by}} "
+            f"{story.descendants:>{col_comments}} "
+            f"{story.age:>{col_age}}"
+        )
+
+
+def print_comments_list(comments: list) -> None:
+    """Print comments in a readable format."""
+    if not comments:
+        print("No comments found.")
+        return
+
+    for i, comment in enumerate(comments, start=1):
+        by = comment.by or "[deleted]"
+        age = comment.age
+        text = comment.text_plain[:200]
+        if len(comment.text_plain) > 200:
+            text += "..."
+        replies = len(comment.kids)
+        reply_note = f" ({replies} replies)" if replies else ""
+
+        print(f"  {i}. {by} — {age}{reply_note}")
+        print(f"     {text}")
+        print()
+
+
+def print_user_profile(user) -> None:
+    """Print user profile in a readable format."""
+    print(f"  Username:    {user.id}")
+    print(f"  Karma:       {user.karma:,}")
+    print(f"  Member since:{user.member_since}")
+    if user.about_plain:
+        about = user.about_plain[:300]
+        if len(user.about_plain) > 300:
+            about += "..."
+        print(f"  About:       {about}")
+    print(f"  Submissions: {len(user.submitted):,}")
+
+
+def print_search_results_table(results: list) -> None:
+    """Print search results as a table."""
+    if not results:
+        print("No results found.")
+        return
+
+    col_id = 10
+    col_title = 55
+    col_pts = 6
+    col_by = 14
+    col_cmts = 6
+
+    header = (
+        f"{'ID':<{col_id}} "
+        f"{'Title':<{col_title}} "
+        f"{'Pts':>{col_pts}} "
+        f"{'By':<{col_by}} "
+        f"{'Cmts':>{col_cmts}}"
+    )
+    print(header)
+    print("-" * len(header))
+
+    for result in results:
+        title = _safe(result.title or "", col_title)
+        by = _safe(result.author, col_by)
+        pts = result.points if result.points is not None else 0
+        cmts = result.num_comments if result.num_comments is not None else 0
+        print(
+            f"{result.objectID:<{col_id}} "
+            f"{title:<{col_title}} "
+            f"{pts:>{col_pts}} "
+            f"{by:<{col_by}} "
+            f"{cmts:>{col_cmts}}"
+        )