cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/credentials.py

@@ -0,0 +1,235 @@
+"""保存 OAuth 凭据：每个用户一个 JSON 文件，按基础 URL 区分站点，并使用排他文件锁保护。
+
+文件结构（``$XDG_CONFIG_HOME/cheso/credentials.json``，默认 ``~/.config/cheso/credentials.json``）::
+
+    {"version": 1, "default_base_url": "https://cheso.ai",
+     "sites": {"https://cheso.ai": {"client_id": "...", "issuer": "...",
+        "token_endpoint": "...", "revocation_endpoint": "...",
+        "access_token": "...", "refresh_token": "...", "expires_at": 1767225600.0,
+        "pending_device": {...}}}}
+
+``pending_device`` 保存等待用户在浏览器输入短码的设备码登录（``cheso login --device``）：
+设备码、用户码、页面、过期时间、轮询间隔 ``interval``（slow_down 增加的间隔会持续保留）、
+连续连接超时累计的退避间隔 ``backoff``（令牌端点正常答复后恢复为 ``interval``），以及最早下次轮询时间
+``next_poll_at``。``cheso login --wait`` 按原节奏继续等待；登录完成、失败或被替换时删除此记录。
+
+文件在权限为 0700 的目录中以 0600 创建，通过临时文件加重命名实现原子替换。
+刷新令牌每次使用后都会轮换；重复使用旧令牌会撤销整个授权，因此每次读改写都必须持有旁边的
+``credentials.json.lock`` 文件锁。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+import time
+from collections.abc import Iterator, Mapping
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cheso_cli.errors import CliError
+
+FILE_NAME = "credentials.json"
+LOCK_SUFFIX = ".lock"
+FORMAT_VERSION = 1
+DEFAULT_KEY = "default_base_url"
+# 一次刷新在整个 HTTP 往返期间持锁；超过此时长通常说明操作已经卡住。
+DEFAULT_LOCK_TIMEOUT = 90.0
+LOCK_POLL_INTERVAL = 0.05
+
+
+def default_config_dir(env: Mapping[str, str] | None = None) -> Path:
+    env = os.environ if env is None else env
+    base = env.get("XDG_CONFIG_HOME", "").strip()
+    root = Path(base) if base and Path(base).is_absolute() else Path.home() / ".config"
+    return root / "cheso"
+
+
+@dataclass
+class SiteCredentials:
+    """CLI 为单个站点保存的凭据。退出登录后保留 ``client_id``，以便下次登录复用注册信息。"""
+
+    client_id: str = ""
+    issuer: str = ""
+    token_endpoint: str = ""
+    revocation_endpoint: str = ""
+    access_token: str = ""
+    refresh_token: str = ""
+    expires_at: float = 0.0
+    pending_device: dict[str, Any] = field(default_factory=dict)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> SiteCredentials:
+        if not isinstance(raw, dict):
+            return cls()
+        known = {
+            "client_id",
+            "issuer",
+            "token_endpoint",
+            "revocation_endpoint",
+            "access_token",
+            "refresh_token",
+            "expires_at",
+            "pending_device",
+        }
+        try:
+            expires_at = float(raw.get("expires_at") or 0)
+        except (TypeError, ValueError):
+            expires_at = 0.0
+        pending = raw.get("pending_device")
+        return cls(
+            client_id=str(raw.get("client_id") or ""),
+            issuer=str(raw.get("issuer") or ""),
+            token_endpoint=str(raw.get("token_endpoint") or ""),
+            revocation_endpoint=str(raw.get("revocation_endpoint") or ""),
+            access_token=str(raw.get("access_token") or ""),
+            refresh_token=str(raw.get("refresh_token") or ""),
+            expires_at=expires_at,
+            pending_device=dict(pending) if isinstance(pending, dict) else {},
+            extra={k: v for k, v in raw.items() if k not in known},
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        extra = data.pop("extra")
+        if not data["pending_device"]:
+            data.pop("pending_device")
+        return {**extra, **data}
+
+    @property
+    def logged_in(self) -> bool:
+        return bool(self.access_token or self.refresh_token)
+
+    def clear_tokens(self) -> None:
+        self.access_token = ""
+        self.refresh_token = ""
+        self.expires_at = 0.0
+
+
+class CredentialStore:
+    """读写凭据文件；修改文件的调用方必须持有 :meth:`locked` 对应的锁。"""
+
+    def __init__(self, path: Path | None = None, *, lock_timeout: float = DEFAULT_LOCK_TIMEOUT) -> None:
+        self.path = Path(path) if path is not None else default_config_dir() / FILE_NAME
+        self.lock_path = self.path.with_name(self.path.name + LOCK_SUFFIX)
+        self.lock_timeout = lock_timeout
+
+    # ---- 读取 ----
+
+    def read(self) -> dict[str, Any]:
+        """读取完整文档；文件不存在或无法读取时返回空内容。"""
+        try:
+            raw = self.path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {"version": FORMAT_VERSION, "sites": {}}
+        except OSError as e:
+            raise CliError(f"cannot read {self.path}: {e.strerror or e}") from e
+        try:
+            data = json.loads(raw)
+        except ValueError:
+            print(f"warning: ignoring unreadable credentials file {self.path}", file=sys.stderr)
+            return {"version": FORMAT_VERSION, "sites": {}}
+        if not isinstance(data, dict) or not isinstance(data.get("sites"), dict):
+            return {"version": FORMAT_VERSION, "sites": {}}
+        return data
+
+    def get(self, base_url: str) -> SiteCredentials:
+        return SiteCredentials.from_dict(self.read()["sites"].get(base_url))
+
+    # ---- 写入（需要持锁）----
+
+    def default_base_url(self) -> str:
+        """最近一次 ``cheso login`` 的站点；命令未明确指定站点时使用它。"""
+        value = self.read().get(DEFAULT_KEY)
+        return value if isinstance(value, str) else ""
+
+    def put(self, base_url: str, creds: SiteCredentials, *, make_default: bool = False) -> None:
+        data = self.read()
+        data["version"] = FORMAT_VERSION
+        data["sites"][base_url] = creds.to_dict()
+        if make_default:
+            data[DEFAULT_KEY] = base_url
+        self._write(data)
+
+    def _write(self, data: dict[str, Any]) -> None:
+        self._ensure_dir()
+        payload = json.dumps(data, indent=2, sort_keys=True).encode("utf-8")
+        fd, tmp = tempfile.mkstemp(prefix=".credentials-", suffix=".tmp", dir=self.path.parent)
+        try:
+            with os.fdopen(fd, "wb") as f:
+                os.chmod(tmp, 0o600)
+                f.write(payload)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, self.path)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+        with contextlib.suppress(OSError):
+            os.chmod(self.path, 0o600)
+
+    def _ensure_dir(self) -> None:
+        directory = self.path.parent
+        directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        with contextlib.suppress(OSError):
+            os.chmod(directory, 0o700)
+
+    # ---- 加锁 ----
+
+    @contextlib.contextmanager
+    def locked(self) -> Iterator[None]:
+        """跨进程、跨线程的排他锁；每个持锁者单独打开锁文件。"""
+        self._ensure_dir()
+        fd = os.open(self.lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            _acquire(fd, self.lock_timeout, self.lock_path)
+            try:
+                yield
+            finally:
+                _release(fd)
+        finally:
+            os.close(fd)
+
+
+if sys.platform == "win32":  # pragma: no cover - 仅在 Windows 上执行
+    import msvcrt
+
+    def _try_lock(fd: int) -> bool:
+        os.lseek(fd, 0, os.SEEK_SET)
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError:
+            return False
+        return True
+
+    def _release(fd: int) -> None:
+        os.lseek(fd, 0, os.SEEK_SET)
+        with contextlib.suppress(OSError):
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+
+else:
+    import fcntl
+
+    def _try_lock(fd: int) -> bool:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            return False
+        return True
+
+    def _release(fd: int) -> None:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+def _acquire(fd: int, timeout: float, path: Path) -> None:
+    deadline = time.monotonic() + timeout
+    while not _try_lock(fd):
+        if time.monotonic() >= deadline:
+            raise CliError(f"timed out waiting for the credentials lock {path}; another cheso command may be stuck")
+        time.sleep(LOCK_POLL_INTERVAL)

cheso_cli/errors.py

@@ -0,0 +1,56 @@
+"""定义退出码，以及各命令用于按指定退出码终止执行的错误类型。"""
+
+from __future__ import annotations
+
+import enum
+from typing import Any
+
+
+class ExitCode(enum.IntEnum):
+    """进程退出码，属于 README、SKILL.md 约定的公开接口，不能重新编号。"""
+
+    OK = 0
+    ERROR = 1
+    USAGE = 2
+    NEEDS_INPUT = 3
+    LOGIN_REQUIRED = 4
+    INSUFFICIENT_CREDITS = 5
+    WAIT_TIMEOUT = 6
+    RETRYABLE = 7
+    DOWNLOAD_FAILED = 8
+
+
+class CliError(Exception):
+    """使当前命令以 ``exit_code`` 退出的错误。
+
+    ``kind`` 是稳定的机器可读标签，例如 ``login_required``、``project_busy``；
+    ``extra`` 为 ``--json`` 输出提供结构化字段，例如 ``running_task_id``、``topup_url``。
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: ExitCode = ExitCode.ERROR,
+        kind: str = "error",
+        extra: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.kind = kind
+        self.extra = dict(extra or {})
+
+
+class LoginRequired(CliError):
+    """没有可用凭据；用户需要运行 ``cheso login`` 或提供令牌。"""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, exit_code=ExitCode.LOGIN_REQUIRED, kind="login_required")
+
+
+class UsageError(CliError):
+    """命令行参数错误，例如选项值无效或缺少参数。"""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, exit_code=ExitCode.USAGE, kind="usage")

cheso_cli/legacy_commands.py

@@ -0,0 +1,93 @@
+"""第一版留下的底层接口命令（profile / project / session / plan）：原样输出接口返回的 JSON。"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from cheso_cli.errors import ExitCode
+
+if TYPE_CHECKING:
+    from cheso_cli.cli import Context
+
+
+def _legacy_json(ctx: Context, data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2), file=ctx.out)
+
+
+def cmd_profile(ctx: Context) -> int:
+    _legacy_json(ctx, ctx.client.profile())
+    return ExitCode.OK
+
+
+def cmd_project_create(ctx: Context) -> int:
+    data = ctx.client.project_create(description=ctx.args.description)
+    _legacy_json(ctx, data)
+    if isinstance(data, dict) and data.get("project_id"):
+        print(f"project_id={data['project_id']}", file=ctx.err)
+    return ExitCode.OK
+
+
+def _tri_bool(value: str | None) -> bool | None:
+    return None if value is None else value == "true"
+
+
+def cmd_project_list(ctx: Context) -> int:
+    a = ctx.args
+    _legacy_json(
+        ctx,
+        ctx.client.project_list(
+            status=a.status, starred=_tri_bool(a.starred), sort_by=a.sort_by, page=a.page, page_size=a.page_size
+        ),
+    )
+    return ExitCode.OK
+
+
+def cmd_project_get(ctx: Context) -> int:
+    _legacy_json(ctx, ctx.client.project_get(ctx.args.project_id))
+    return ExitCode.OK
+
+
+def cmd_project_update(ctx: Context) -> int:
+    a = ctx.args
+    _legacy_json(
+        ctx,
+        ctx.client.project_update(
+            a.project_id,
+            description=a.description,
+            starred=_tri_bool(a.starred),
+            cover_file_id=a.cover_file_id,
+            cover_file_version=a.cover_file_version,
+        ),
+    )
+    return ExitCode.OK
+
+
+def cmd_project_delete(ctx: Context) -> int:
+    data = ctx.client.project_delete(ctx.args.project_id)
+    _legacy_json(ctx, data if data is not None else {"ok": True})
+    return ExitCode.OK
+
+
+def cmd_project_fork(ctx: Context) -> int:
+    data = ctx.client.project_fork(ctx.args.project_id, description=ctx.args.description)
+    _legacy_json(ctx, data)
+    if isinstance(data, dict) and data.get("project_id"):
+        print(f"project_id={data['project_id']}", file=ctx.err)
+    return ExitCode.OK
+
+
+def cmd_session_create(ctx: Context) -> int:
+    _legacy_json(ctx, ctx.client.session_create(project_id=ctx.args.project_id, title=ctx.args.title))
+    return ExitCode.OK
+
+
+def cmd_plan_create(ctx: Context) -> int:
+    a = ctx.args
+    _legacy_json(ctx, ctx.client.plan_create(prompt=a.prompt, project_id=a.project_id, session_id=a.session_id))
+    return ExitCode.OK
+
+
+def cmd_plan_get(ctx: Context) -> int:
+    _legacy_json(ctx, ctx.client.plan_get(ctx.args.plan_id))
+    return ExitCode.OK