netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/feishu_app_onboarding.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Create or update the Bot-only Feishu/Lark app used by Netizen.
+
+This helper runs in the selected installation without requiring Lark CLI.
+Its stdout is a private machine-readable credential channel consumed by setup;
+all user-facing progress goes to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, IO
+
+
+REQUIRED_TENANT_SCOPES = (
+    "im:message",
+    "im:message.group_msg",
+    "im:message.group_at_msg.include_bot:readonly",
+    "im:message.p2p_msg:readonly",
+    "im:chat:read",
+    "im:chat.members:read",
+    "im:resource",
+    "im:message:send_as_bot",
+)
+TENANT_SCOPE_ALTERNATIVES = {
+    "im:chat:read": frozenset(("im:chat", "im:chat:read", "im:chat:readonly")),
+}
+TENANT_EVENTS = ("im.message.receive_v1",)
+CALLBACKS = ("card.action.trigger",)
+
+
+class OnboardingError(RuntimeError):
+    """The registration flow did not return a safe credential pair."""
+
+
+RegisterApp = Callable[..., Mapping[str, Any]]
+QrRenderer = Callable[[str, IO[str]], None]
+
+
+def _registration_options(app_id: str | None) -> dict[str, Any]:
+    options: dict[str, Any] = {
+        "source": "netizen-installer",
+        "app_preset": {
+            "name": "{user}'s Netizen",
+            "desc": "Use native Codex threads from Feishu or Lark.",
+        },
+        "addons": {
+            "preset": False,
+            "scopes": {"tenant": list(REQUIRED_TENANT_SCOPES)},
+            "events": {"items": {"tenant": list(TENANT_EVENTS)}},
+            "callbacks": {"items": list(CALLBACKS)},
+        },
+    }
+    if app_id is not None:
+        options["app_id"] = app_id
+    return options
+
+
+def _default_qr_renderer(url: str, output: IO[str]) -> None:
+    import qrcode
+
+    code = qrcode.QRCode(
+        error_correction=qrcode.constants.ERROR_CORRECT_L,
+        border=2,
+    )
+    code.add_data(url)
+    code.make(fit=True)
+    code.print_ascii(out=output, tty=output.isatty(), invert=True)
+
+
+def _credential_payload(result: Mapping[str, Any]) -> dict[str, str | int]:
+    app_id = result.get("client_id")
+    app_secret = result.get("client_secret")
+    if (
+        not isinstance(app_id, str)
+        or not app_id.startswith("cli_")
+        or app_id.strip() != app_id
+        or any(ord(character) < 0x20 for character in app_id)
+    ):
+        raise OnboardingError("registration returned an invalid App ID")
+    if (
+        not isinstance(app_secret, str)
+        or not app_secret
+        or app_secret.strip() != app_secret
+        or any(ord(character) < 0x20 for character in app_secret)
+    ):
+        raise OnboardingError("registration returned an invalid App Secret")
+    return {"version": 1, "appId": app_id, "appSecret": app_secret}
+
+
+def run_registration(
+    app_id: str | None,
+    *,
+    register_app: RegisterApp,
+    render_qr: QrRenderer = _default_qr_renderer,
+    stdout: IO[str] | None = None,
+    stderr: IO[str] | None = None,
+) -> None:
+    """Run one official device flow and emit credentials only on success."""
+
+    credential_output = sys.stdout if stdout is None else stdout
+    progress_output = sys.stderr if stderr is None else stderr
+    if app_id is not None and not app_id.startswith("cli_"):
+        raise OnboardingError("existing App ID must start with cli_")
+
+    def on_qr_code(info: Mapping[str, Any]) -> None:
+        url = info.get("url")
+        if not isinstance(url, str) or not url.startswith("https://"):
+            raise OnboardingError("registration returned an invalid verification URL")
+        print("", file=progress_output)
+        print(
+            "Open this Feishu/Lark URL and confirm the requested Bot access:",
+            file=progress_output,
+        )
+        print(url, file=progress_output)
+        print("Or scan this QR code:", file=progress_output)
+        try:
+            render_qr(url, progress_output)
+        except Exception:
+            print(
+                "(QR rendering is unavailable; use the URL above.)",
+                file=progress_output,
+            )
+        print(
+                "Keep netizen setup running while completing the browser confirmation. "
+            "Agents: send the verification URL to the user, retain this process, "
+            "and continue reading its output after confirmation. "
+            "The link expires after about 10 minutes; rerun setup if it expires. "
+            "App credentials are saved automatically; do not request or send the "
+            "App Secret in chat.",
+            file=progress_output,
+        )
+        progress_output.flush()
+
+    def on_status_change(info: Mapping[str, Any]) -> None:
+        status = info.get("status")
+        if status == "domain_switched":
+            print("Continuing with the Lark account domain...", file=progress_output)
+        elif status == "slow_down":
+            print("Waiting for confirmation...", file=progress_output)
+
+    result = register_app(
+        on_qr_code=on_qr_code,
+        on_status_change=on_status_change,
+        **_registration_options(app_id),
+    )
+    payload = _credential_payload(result)
+    if app_id is not None and payload["appId"] != app_id:
+        raise OnboardingError("registration returned a different App ID")
+    json.dump(payload, credential_output, ensure_ascii=True, separators=(",", ":"))
+    credential_output.write("\n")
+    credential_output.flush()
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Netizen Feishu/Lark app onboarding")
+    parser.add_argument("--app-id", help="update this existing cli_ application")
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        import lark_oapi as lark
+
+        run_registration(args.app_id, register_app=lark.register_app)
+        return 0
+    except KeyboardInterrupt:
+        print("netizen: Feishu/Lark app setup interrupted", file=sys.stderr)
+        return 130
+    except Exception:
+        # Credential material is only emitted after complete validation.  Keep
+        # failures generic so an unexpected SDK exception can never echo a
+        # sensitive response into the terminal or installer logs.
+        print(
+            "netizen: Feishu/Lark app setup did not complete; "
+            "rerun netizen setup or choose manual credentials",
+            file=sys.stderr,
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

netizen_cli/feishu_app_permissions.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Check the effective tenant permission contract for the configured app."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any, IO
+
+
+from .feishu_app_onboarding import (
+    REQUIRED_TENANT_SCOPES,
+    TENANT_SCOPE_ALTERNATIVES,
+)
+from .lark_app import load_lark_app
+
+
+class PermissionCheckError(RuntimeError):
+    """The platform did not return a trustworthy tenant permission state."""
+
+
+ScopeLister = Callable[[], Any]
+
+
+def _missing_required_scopes(response: Any) -> tuple[str, ...]:
+    success = getattr(response, "success", None)
+    if not callable(success) or not success():
+        raise PermissionCheckError("the tenant permission query failed")
+    data = getattr(response, "data", None)
+    scopes = getattr(data, "scopes", None)
+    if not isinstance(scopes, list):
+        raise PermissionCheckError("the tenant permission query returned invalid data")
+
+    granted: set[str] = set()
+    for scope in scopes:
+        name = getattr(scope, "scope_name", None)
+        status = getattr(scope, "grant_status", None)
+        scope_type = getattr(scope, "scope_type", None)
+        if (
+            not isinstance(name, str)
+            or not name
+            or isinstance(status, bool)
+            or not isinstance(status, int)
+            or scope_type not in {"tenant", "user"}
+        ):
+            raise PermissionCheckError(
+                "the tenant permission query returned an invalid scope"
+            )
+        if scope_type == "tenant" and status == 1:
+            granted.add(name)
+    return tuple(
+        scope
+        for scope in REQUIRED_TENANT_SCOPES
+        if not (TENANT_SCOPE_ALTERNATIVES.get(scope, frozenset((scope,))) & granted)
+    )
+
+
+def run_permission_check(
+    *,
+    list_scopes: ScopeLister,
+    stdout: IO[str] | None = None,
+) -> None:
+    output = sys.stdout if stdout is None else stdout
+    missing = _missing_required_scopes(list_scopes())
+    print(
+        json.dumps(
+            {"version": 1, "missingScopes": list(missing)},
+            separators=(",", ":"),
+        ),
+        file=output,
+    )
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--lark-app-config", type=Path, required=True)
+    return parser.parse_args(argv)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    client_factory: Callable[[str, str], Any] | None = None,
+) -> int:
+    args = parse_args(argv)
+    try:
+        credentials = load_lark_app(args.lark_app_config)
+        if client_factory is None:
+            import lark_oapi as lark
+            from lark_oapi.api.application.v6 import ListScopeRequest
+
+            client = (
+                lark.Client.builder()
+                .app_id(credentials.app_id)
+                .app_secret(credentials.app_secret)
+                .log_level(lark.LogLevel.ERROR)
+                .timeout(15)
+                .build()
+            )
+        else:
+            client = client_factory(credentials.app_id, credentials.app_secret)
+
+        def list_scopes() -> Any:
+            if client_factory is None:
+                request = ListScopeRequest.builder().build()
+            else:
+                request = None
+            return client.application.v6.scope.list(request)
+
+        run_permission_check(list_scopes=list_scopes)
+    except KeyboardInterrupt:
+        return 130
+    except Exception:
+        print("Feishu/Lark permission verification did not complete.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

netizen_cli/git_status.py

@@ -0,0 +1,63 @@
+"""Bounded, read-only Git status for Project display."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+
+_GIT_STATUS_TIMEOUT_SECONDS = 2.0
+_BRANCH_HEADER_PREFIX = "## "
+
+
+async def git_branch_status(cwd: Path) -> str | None:
+    """Return Git's porcelain branch header content for ``cwd`` when available."""
+
+    process: asyncio.subprocess.Process | None = None
+    try:
+        async with asyncio.timeout(_GIT_STATUS_TIMEOUT_SECONDS):
+            process = await asyncio.create_subprocess_exec(
+                "git",
+                "--no-optional-locks",
+                "-C",
+                str(cwd),
+                "-c",
+                "core.fsmonitor=false",
+                "status",
+                "--porcelain=v1",
+                "--branch",
+                "--untracked-files=no",
+                "--ignore-submodules=all",
+                "--",
+                ".git",
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            stdout, _stderr = await process.communicate()
+    except asyncio.CancelledError:
+        if process is not None:
+            await _kill_and_reap(process)
+        raise
+    except (OSError, TimeoutError):
+        if process is not None:
+            await _kill_and_reap(process)
+        return None
+    if process.returncode != 0:
+        return None
+    header, _, _remainder = stdout.decode(
+        "utf-8", errors="replace"
+    ).partition("\n")
+    if not header.startswith(_BRANCH_HEADER_PREFIX):
+        return None
+    status = header.removeprefix(_BRANCH_HEADER_PREFIX).strip()
+    return status or None
+
+
+async def _kill_and_reap(process: asyncio.subprocess.Process) -> None:
+    if process.returncode is None:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+    await process.wait()