aukeys-opscli 0.0.6__py3-none-any.whl

opscli/auth/domain/exceptions.py

@@ -0,0 +1,33 @@
+"""auth 异常定义。"""
+
+
+class AuthError(Exception):
+    """基础认证异常"""
+
+
+class NotAuthenticatedError(AuthError):
+    """未登录或 session 已失效"""
+
+
+class SessionExpiredError(AuthError):
+    """session_id 已过期"""
+
+
+class TokenFetchError(AuthError):
+    """从业务系统获取 JWT 失败"""
+
+
+class SystemNotFoundError(AuthError):
+    """系统别名未注册"""
+
+
+class DeviceFlowError(AuthError):
+    """Device Flow 授权流程异常"""
+
+
+class DeviceFlowExpiredError(DeviceFlowError):
+    """设备码已超时"""
+
+
+class DeviceFlowDeniedError(DeviceFlowError):
+    """用户拒绝授权"""

opscli/auth/exceptions.py

@@ -0,0 +1,23 @@
+"""auth exceptions 兼容导出。"""
+
+from opscli.auth.domain.exceptions import (
+    AuthError,
+    DeviceFlowDeniedError,
+    DeviceFlowError,
+    DeviceFlowExpiredError,
+    NotAuthenticatedError,
+    SessionExpiredError,
+    SystemNotFoundError,
+    TokenFetchError,
+)
+
+__all__ = [
+    "AuthError",
+    "NotAuthenticatedError",
+    "SessionExpiredError",
+    "TokenFetchError",
+    "SystemNotFoundError",
+    "DeviceFlowError",
+    "DeviceFlowExpiredError",
+    "DeviceFlowDeniedError",
+]

opscli/auth/storage/__init__.py

@@ -0,0 +1 @@
+# storage 模块

opscli/auth/storage/credential_store.py

@@ -0,0 +1,163 @@
+"""凭证存储模块。
+
+采用双层存储策略（铁律5）：
+- 优先使用系统 Keychain（macOS 钥匙串 / Linux Secret Service）
+- Keychain 不可用时兜底使用 AES-256-GCM 加密文件（credentials.bin）
+
+存储结构（JSON）：
+{
+    "session_id": "...",          # 登录 session
+    "device_code": "...",         # Device Flow 设备码
+    "email": "...",               # 用户邮箱
+    "session_expires_at": "...",  # session 过期时间（ISO 格式）
+    "tokens": {                   # 各系统 JWT
+        "<system_key>": {
+            "jwt": "...",
+            "expires_at": "...",  # JWT 过期时间（ISO 格式）
+            "saved_at": 1234567890
+        }
+    }
+}
+"""
+import json
+import time
+import stat
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from cryptography.exceptions import InvalidTag
+from opscli.auth.storage.crypto import Crypto
+
+try:
+    import keyring
+    import keyring.errors
+    _KEYRING_AVAILABLE = True
+except Exception:
+    _KEYRING_AVAILABLE = False
+
+# Keychain 服务名和账户名（铁律5：不可随意更改，否则用户凭证丢失）
+_KEYRING_SERVICE = "opscli-auth"
+_KEYRING_ACCOUNT = "credentials"
+
+
+class CredentialStore:
+    """凭证存储管理器，负责 session 和 JWT 的持久化读写。
+
+    存储策略：Keychain 优先，AES-256-GCM 加密文件兜底。
+    测试环境通过传入 base_dir 参数跳过 Keychain（铁律8）。
+    """
+
+    def __init__(self, base_dir: Path | None = None):
+        """
+        Args:
+            base_dir: 存储目录，传入时跳过 Keychain（用于测试），
+                      默认使用 CONFIG_DIR（~/.config/opscli/）
+        """
+        # 仅默认路径启用 Keychain；显式传入 base_dir（如测试）走文件存储
+        self._use_keyring = _KEYRING_AVAILABLE and base_dir is None
+        from opscli.config import CONFIG_DIR
+        self._dir = Path(base_dir or CONFIG_DIR)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / "credentials.bin"
+        self._crypto = Crypto(self._dir / ".key")
+
+    @property
+    def base_dir(self) -> Path:
+        """返回存储目录路径，供 TokenManager 构建文件锁路径。"""
+        return self._dir
+
+    def load(self) -> dict | None:
+        """加载凭证数据，返回完整凭证字典或 None（无凭证时）。
+
+        读取优先级：系统 Keychain > AES-256-GCM 加密文件。
+        加密文件解密失败（密钥不匹配）时自动清除损坏文件。
+        """
+        # 优先从系统 Keychain 读取
+        if self._use_keyring:
+            try:
+                raw = keyring.get_password(_KEYRING_SERVICE, _KEYRING_ACCOUNT)
+                if raw:
+                    return json.loads(raw)
+            except keyring.errors.NoKeyringError:
+                pass
+            except Exception:
+                pass
+
+        # 兜底：从加密文件读取
+        if not self._path.exists():
+            return None
+        try:
+            return json.loads(self._crypto.decrypt(self._path.read_bytes()))
+        except (InvalidTag, Exception):
+            # 密钥与密文不匹配（如密钥轮换/环境变更），清除损坏的凭证文件重新开始
+            self._path.unlink(missing_ok=True)
+            return None
+
+    def _save(self, data: dict):
+        """持久化凭证数据，写入 Keychain 或加密文件。"""
+        raw = json.dumps(data)
+        # 优先写入系统 Keychain
+        if self._use_keyring:
+            try:
+                keyring.set_password(_KEYRING_SERVICE, _KEYRING_ACCOUNT, raw)
+                return
+            except keyring.errors.NoKeyringError:
+                pass
+            except Exception:
+                pass
+
+        # 兜底：写入加密文件
+        self._path.write_bytes(self._crypto.encrypt(raw))
+        self._path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    def save_session(
+        self,
+        session_id: str,
+        email: str,
+        expires_at: str,
+        device_code: str | None = None,
+    ):
+        """保存登录 session 信息。
+
+        当登录态切换（如重新登录其他账号或新的 session）时，必须清空旧 JWT，
+        避免后续请求继续复用上一位用户的缓存 token。
+        """
+        data = self.load() or {}
+        session_changed = (
+            (data.get("session_id") and data.get("session_id") != session_id)
+            or (data.get("email") and data.get("email") != email)
+        )
+        data.update({
+            "session_id": session_id,
+            "email": email,
+            "session_expires_at": expires_at,
+            "tokens": {} if session_changed else data.get("tokens", {}),
+        })
+        # device_code 缺失时保留旧值，兼容历史凭证数据
+        if device_code is not None:
+            data["device_code"] = device_code
+        self._save(data)
+
+    def save_token(self, system_key: str, jwt: str, expires_in: int):
+        """保存指定系统的 JWT，将 expires_in（秒）转换为 ISO 格式的 expires_at。"""
+        data = self.load() or {}
+        data.setdefault("tokens", {})
+        expires_at = (
+            datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+        ).isoformat()
+        data["tokens"][system_key] = {
+            "jwt": jwt,
+            "expires_at": expires_at,
+            "saved_at": int(time.time()),
+        }
+        self._save(data)
+
+    def clear(self):
+        # 清除 Keychain
+        if self._use_keyring:
+            try:
+                keyring.delete_password(_KEYRING_SERVICE, _KEYRING_ACCOUNT)
+            except Exception:
+                pass
+        # 清除加密文件
+        if self._path.exists():
+            self._path.unlink()

opscli/auth/storage/crypto.py

@@ -0,0 +1,67 @@
+"""AES-256-GCM 加密工具模块。
+
+为凭证文件提供对称加密能力，密钥自动生成并存储在本地文件中。
+加密格式：[12 字节随机 nonce] + [AES-GCM 密文]，解密时按前 12 字节切割 nonce。
+"""
+import os
+import stat
+from pathlib import Path
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+class Crypto:
+    """AES-256-GCM 加密器，管理密钥的生成、加载和加解密操作。
+
+    密钥文件首次使用时自动生成（256 位），存储权限为 600（仅属主可读写）。
+    """
+
+    def __init__(self, key_path: Path):
+        """
+        Args:
+            key_path: 密钥文件路径，不存在时自动创建
+        """
+        self._key_path = Path(key_path)
+        self._key = self._load_or_create_key()
+
+    def _load_or_create_key(self) -> bytes:
+        """加载已有密钥，或首次使用时生成 256 位 AES 密钥并持久化。"""
+        if self._key_path.exists():
+            return self._key_path.read_bytes()
+        # 生成 256 位随机密钥
+        key = AESGCM.generate_key(bit_length=256)
+        self._key_path.write_bytes(key)
+        # 权限设为 600（仅属主可读写），防止其他用户读取密钥
+        self._key_path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        return key
+
+    def encrypt(self, plaintext: str) -> bytes:
+        """加密明文字符串。
+
+        使用 12 字节（96 位）随机 nonce，拼接格式为 nonce + ciphertext。
+        96 位 nonce 是 NIST 推荐的 GCM nonce 长度，可保证安全性和性能。
+
+        Args:
+            plaintext: 待加密的明文字符串
+
+        Returns:
+            bytes: nonce(12B) + AES-GCM 密文
+        """
+        nonce = os.urandom(12)  # 96 位随机 nonce
+        return nonce + AESGCM(self._key).encrypt(nonce, plaintext.encode(), None)
+
+    def decrypt(self, ciphertext: bytes) -> str:
+        """解密密文，还原为明文字符串。
+
+        按约定前 12 字节为 nonce，剩余部分为 AES-GCM 密文。
+
+        Args:
+            ciphertext: nonce(12B) + AES-GCM 密文
+
+        Returns:
+            str: 解密后的明文
+
+        Raises:
+            cryptography.exceptions.InvalidTag: 密钥不匹配或数据被篡改
+        """
+        return AESGCM(self._key).decrypt(ciphertext[:12], ciphertext[12:], None).decode()

opscli/cli.py

@@ -0,0 +1,36 @@
+"""opscli 顶级 CLI 入口。
+
+基于 Typer 框架，注册所有子模块命令组（auth、skills 等）。
+"""
+import typer
+from opscli.amazon.cli import app as amazon_app
+from opscli.auth.cli import app as auth_app
+from opscli.query.cli import app as query_app
+from opscli.skills.cli import app as skills_app
+from opscli.version import get_version
+
+
+def _version_callback(value: bool):
+    """处理 --version/-V 标志，打印版本号后立即退出。"""
+    if value:
+        typer.echo(f"opscli v{get_version()}")
+        raise typer.Exit()
+
+
+app = typer.Typer(help="Aukeys 运营 CLI 工具集")
+
+# 模块注册：每新增一个子模块只需在此追加一行（铁律1）
+app.add_typer(auth_app, name="auth")
+app.add_typer(amazon_app, name="amazon")
+app.add_typer(query_app, name="query")
+app.add_typer(skills_app, name="skills")
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None, "--version", "-V", help="显示版本信息",
+        callback=_version_callback, is_eager=True,
+    ),
+):
+    """主回调：为顶级全局选项预留入口。"""

opscli/config.py

@@ -0,0 +1,3 @@
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "opscli"

opscli/query/__init__.py

@@ -0,0 +1,6 @@
+"""opscli query 模块导出。"""
+
+from opscli.query.services.manager import QueryManager
+from opscli.query.transport.client import QueryClient
+
+__all__ = ["QueryClient", "QueryManager"]

opscli/query/cli.py

@@ -0,0 +1,5 @@
+"""query CLI 兼容导出。"""
+
+from opscli.query.commands.cli import app
+
+__all__ = ["app"]

opscli/query/client.py

@@ -0,0 +1,5 @@
+"""query client 兼容导出。"""
+
+from opscli.query.transport.client import QueryClient
+
+__all__ = ["QueryClient"]

opscli/query/commands/__init__.py

@@ -0,0 +1 @@
+"""query 命令层。"""

opscli/query/commands/cli.py

@@ -0,0 +1,140 @@
+"""query CLI 子命令定义。"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from opscli.query.domain.exceptions import QueryError
+from opscli.query.services.manager import QueryManager
+
+app = typer.Typer(help="数据查询入口，统一转发远端查询请求")
+
+
+def _emit(payload: dict, pretty: bool) -> None:
+    """统一输出 JSON。"""
+    if pretty:
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        typer.echo(json.dumps(payload, ensure_ascii=False))
+
+
+def _error_payload(command: str, exc: Exception) -> dict:
+    """将异常统一映射为标准错误输出。"""
+    if isinstance(exc, QueryError):
+        error = exc.to_dict()
+    else:
+        error = {
+            "code": "QUERY_ERROR",
+            "message": str(exc),
+        }
+    return {
+        "success": False,
+        "command": command,
+        "data": None,
+        "error": error,
+    }
+
+
+@app.command("metadata")
+def metadata(
+    dataset: str | None = typer.Option(None, "--dataset", help="dataset_alias"),
+    table_id: int | None = typer.Option(None, "--table-id", help="table_id"),
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定 Skill 目录"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """读取指定数据集的 query metadata。"""
+    manager = QueryManager()
+    try:
+        result = manager.metadata(dataset_alias=dataset, table_id=table_id, skills_dir=skills_dir)
+        payload = {
+            "success": True,
+            "command": "query metadata",
+            "data": result.to_dict(),
+            "error": None,
+        }
+    except Exception as exc:
+        _emit(_error_payload("query metadata", exc), pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)
+
+
+@app.command("run")
+def run(
+    payload_path: str = typer.Option(..., "--payload", help="查询 JSON 文件路径"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """执行查询并转发到服务端 cli-query。"""
+    manager = QueryManager()
+    try:
+        result = manager.run(payload_path=payload_path)
+        payload = {
+            "success": True,
+            "command": "query run",
+            "data": result,
+            "error": None,
+        }
+    except Exception as exc:
+        _emit(_error_payload("query run", exc), pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)
+
+
+@app.command("build")
+def build(
+    dataset: str | None = typer.Option(None, "--dataset", help="dataset_alias"),
+    table_id: int | None = typer.Option(None, "--table-id", help="table_id"),
+    dimension: list[str] | None = typer.Option(None, "--dimension", help="维度定义：field_name[:alias]"),
+    metric: list[str] | None = typer.Option(None, "--metric", help="指标定义：field_name:aggregation[:alias]"),
+    where: list[str] | None = typer.Option(None, "--where", help="筛选条件：field|operator|value_json，可重复"),
+    where_json: str | None = typer.Option(None, "--where-json", help="where JSON 字符串"),
+    where_file: str | None = typer.Option(None, "--where-file", help="where JSON 文件路径"),
+    having: list[str] | None = typer.Option(None, "--having", help="having 条件：expr|operator|value_json，可重复"),
+    order_by: list[str] | None = typer.Option(None, "--order-by", help="排序定义：expr[:asc|desc]"),
+    limit: int = typer.Option(20, "--limit", help="limit，默认 20"),
+    offset: int = typer.Option(0, "--offset", help="offset，默认 0"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="仅生成 SQL，不执行查询"),
+    output: str | None = typer.Option(None, "--output", help="将 payload 写入指定文件"),
+    data_comparison: str | None = typer.Option(
+        None, "--data-comparison",
+        help="数据对比：field,start_date,end_date（例: date_id,2026-03-01,2026-03-22）",
+    ),
+    run: bool = typer.Option(False, "--run", help="构造后立即执行查询"),
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定 Skill 目录"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """基于简化参数构造标准 query payload。"""
+    manager = QueryManager()
+    try:
+        common_kwargs = {
+            "dataset_alias": dataset,
+            "table_id": table_id,
+            "dimensions": dimension,
+            "metrics": metric,
+            "where_conditions": where,
+            "where_json": where_json,
+            "where_file": where_file,
+            "having_conditions": having,
+            "order_by": order_by,
+            "limit": limit,
+            "offset": offset,
+            "dry_run": dry_run,
+            "output_path": output,
+            "data_comparison": data_comparison,
+            "skills_dir": skills_dir,
+        }
+        result = manager.build_and_run(**common_kwargs) if run else manager.build(**common_kwargs)
+        payload = {
+            "success": True,
+            "command": "query build-and-run" if run else "query build",
+            "data": result,
+            "error": None,
+        }
+    except Exception as exc:
+        _emit(_error_payload("query build-and-run" if run else "query build", exc), pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)

opscli/query/domain/__init__.py

@@ -0,0 +1,23 @@
+"""query 领域模型与异常。"""
+
+from opscli.query.domain.exceptions import (
+    BadRemoteJsonError,
+    DatasetNotFoundError,
+    InvalidPayloadError,
+    QueryError,
+    QueryMetadataNotReadyError,
+    RemoteBusinessError,
+    RemoteHttpError,
+)
+from opscli.query.domain.models import QueryMetadataResult
+
+__all__ = [
+    "QueryError",
+    "InvalidPayloadError",
+    "DatasetNotFoundError",
+    "QueryMetadataNotReadyError",
+    "RemoteHttpError",
+    "RemoteBusinessError",
+    "BadRemoteJsonError",
+    "QueryMetadataResult",
+]

opscli/query/domain/exceptions.py

@@ -0,0 +1,73 @@
+"""query 模块异常定义。"""
+
+from __future__ import annotations
+
+
+class QueryError(Exception):
+    """query 模块统一异常基类。"""
+
+    code = "QUERY_ERROR"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+        }
+
+
+class InvalidPayloadError(QueryError):
+    """请求 payload 不合法。"""
+
+    code = "INVALID_PAYLOAD"
+
+
+class DatasetNotFoundError(QueryError):
+    """本地 metadata 中找不到目标数据集。"""
+
+    code = "DATASET_NOT_FOUND"
+
+
+class QueryMetadataNotReadyError(QueryError):
+    """本地 query metadata 尚未准备好。"""
+
+    code = "QUERY_METADATA_NOT_READY"
+
+
+class RemoteHttpError(QueryError):
+    """远端 HTTP 请求失败。"""
+
+    code = "REMOTE_HTTP_ERROR"
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+
+    def to_dict(self) -> dict:
+        payload = super().to_dict()
+        payload["status_code"] = self.status_code
+        return payload
+
+
+class RemoteBusinessError(QueryError):
+    """远端业务层返回失败。"""
+
+    code = "REMOTE_BUSINESS_ERROR"
+
+    def __init__(self, business_code: int | str, message: str):
+        super().__init__(message)
+        self.business_code = business_code
+
+    def to_dict(self) -> dict:
+        payload = super().to_dict()
+        payload["business_code"] = self.business_code
+        return payload
+
+
+class BadRemoteJsonError(QueryError):
+    """远端返回非法 JSON。"""
+
+    code = "BAD_REMOTE_JSON"

opscli/query/domain/models.py

@@ -0,0 +1,21 @@
+"""query 模块数据模型。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class QueryMetadataResult:
+    """query metadata 查询结果。"""
+
+    dataset: dict
+    fields: list[dict]
+    source: str
+
+    def to_dict(self) -> dict:
+        return {
+            "dataset": self.dataset,
+            "fields": self.fields,
+            "source": self.source,
+        }

opscli/query/exceptions.py

@@ -0,0 +1,21 @@
+"""query exceptions 兼容导出。"""
+
+from opscli.query.domain.exceptions import (
+    BadRemoteJsonError,
+    DatasetNotFoundError,
+    InvalidPayloadError,
+    QueryError,
+    QueryMetadataNotReadyError,
+    RemoteBusinessError,
+    RemoteHttpError,
+)
+
+__all__ = [
+    "QueryError",
+    "InvalidPayloadError",
+    "DatasetNotFoundError",
+    "QueryMetadataNotReadyError",
+    "RemoteHttpError",
+    "RemoteBusinessError",
+    "BadRemoteJsonError",
+]

opscli/query/manager.py

@@ -0,0 +1,5 @@
+"""query manager 兼容导出。"""
+
+from opscli.query.services.manager import QueryManager
+
+__all__ = ["QueryManager"]

opscli/query/models.py

@@ -0,0 +1,5 @@
+"""query models 兼容导出。"""
+
+from opscli.query.domain.models import QueryMetadataResult
+
+__all__ = ["QueryMetadataResult"]

opscli/query/services/__init__.py

@@ -0,0 +1,5 @@
+"""query 服务层。"""
+
+from opscli.query.services.manager import QueryManager
+
+__all__ = ["QueryManager"]