maxc-cli 0.1.0__py3-none-any.whl

maxc_cli/store.py

@@ -0,0 +1,123 @@
+
+import json
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Generator
+from uuid import uuid4
+
+try:
+    import fcntl
+    _HAS_FCNTL = True
+except ImportError:
+    _HAS_FCNTL = False
+
+from .exceptions import NotFoundError
+from .utils import now_utc_iso
+
+
+class JobStore:
+    def __init__(self, state_dir: 'Path') -> 'None':
+        self.state_dir = state_dir
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.state_dir / "jobs.json"
+
+    @contextmanager
+    def _locked(self, exclusive: bool = False) -> 'Generator[None, None, None]':
+        """Acquire an advisory file lock (shared for reads, exclusive for writes).
+
+        Falls back to a no-op on platforms without fcntl (e.g. Windows).
+        """
+        if not _HAS_FCNTL:
+            yield
+            return
+        lock_path = self.path.with_suffix(".lock")
+        lock_path.touch(exist_ok=True)
+        fd = lock_path.open("r")
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+            fd.close()
+
+    def create_job(
+        self,
+        *,
+        sql: 'str',
+        project: 'str',
+        result: 'dict[str, Any]',
+        idempotency_key: 'str | None' = None,
+    ) -> 'dict[str, Any]':
+        with self._locked(exclusive=True):
+            payload = self._load()
+            if idempotency_key:
+                existing_id = payload["idempotency"].get(idempotency_key)
+                if existing_id:
+                    return payload["jobs"][existing_id]
+
+            job_id = f"job_{uuid4().hex[:10]}"
+            now = now_utc_iso()
+            job = {
+                "job_id": job_id,
+                "status": "pending",
+                "sql": sql,
+                "project": project,
+                "progress": 0,
+                "submitted_at": now,
+                "updated_at": now,
+                "result": result,
+                "idempotency_key": idempotency_key,
+            }
+            payload["jobs"][job_id] = job
+            if idempotency_key:
+                payload["idempotency"][idempotency_key] = job_id
+            self._save(payload)
+            return job
+
+    def get_job(self, job_id: 'str') -> 'dict[str, Any]':
+        with self._locked():
+            payload = self._load()
+            try:
+                return payload["jobs"][job_id]
+            except KeyError as exc:
+                raise NotFoundError(
+                    f"Job not found: {job_id}",
+                    suggestion="Run `maxc job list` to inspect available jobs.",
+                ) from exc
+
+    def list_jobs(self) -> 'list[dict[str, Any]]':
+        with self._locked():
+            payload = self._load()
+            jobs = list(payload["jobs"].values())
+            jobs.sort(key=lambda item: item["submitted_at"], reverse=True)
+            return jobs
+
+    def update_job(self, job_id: 'str', **changes: 'Any') -> 'dict[str, Any]':
+        with self._locked(exclusive=True):
+            payload = self._load()
+            try:
+                job = payload["jobs"][job_id]
+            except KeyError as exc:
+                raise NotFoundError(
+                    f"Job not found: {job_id}",
+                    suggestion="Run `maxc job list` to inspect available jobs.",
+                ) from exc
+            job.update(changes)
+            job["updated_at"] = now_utc_iso()
+            payload["jobs"][job_id] = job
+            self._save(payload)
+            return job
+
+    def _load(self) -> 'dict[str, Any]':
+        if not self.path.exists():
+            return {"jobs": {}, "idempotency": {}}
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, ValueError):
+            return {"jobs": {}, "idempotency": {}}
+
+    def _save(self, payload: 'dict[str, Any]') -> 'None':
+        self.path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )

maxc_cli/utils.py

@@ -0,0 +1,136 @@
+
+import base64
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .exceptions import ValidationError
+
+
+SQL_COMMENT_RE = re.compile(r"/\*.*?\*/|--[^\n]*", re.DOTALL)
+TABLE_NAME_RE = re.compile(
+    r"(?i)\b(?:from|join|into|update|table)\s+([a-zA-Z_][\w.]*)"
+)
+
+
+def now_utc_iso() -> 'str':
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def deep_merge(base: 'dict[str, Any]', override: 'dict[str, Any]') -> 'dict[str, Any]':
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def resolve_path(raw_path: 'str | None', *, base_dir: 'Path') -> 'Path':
+    if not raw_path:
+        raise ValidationError("Configuration path cannot be empty.")
+    path = Path(raw_path).expanduser()
+    if not path.is_absolute():
+        path = (base_dir / path).resolve()
+    return path
+
+
+def normalize_sql(sql: 'str') -> 'str':
+    stripped = SQL_COMMENT_RE.sub(" ", sql)
+    return " ".join(stripped.strip().split())
+
+
+def detect_operation(sql: 'str') -> 'str':
+    normalized = normalize_sql(sql)
+    match = re.match(r"(?i)^([a-z]+)", normalized)
+    return match.group(1).upper() if match else "UNKNOWN"
+
+
+def extract_table_names(sql: 'str') -> 'list[str]':
+    normalized = normalize_sql(sql)
+    return list(dict.fromkeys(TABLE_NAME_RE.findall(normalized)))
+
+
+def parse_select_projection(sql: 'str') -> 'list[str]':
+    normalized = normalize_sql(sql)
+    match = re.search(r"(?is)^select\s+(.*?)\s+from\b", normalized)
+    if not match:
+        match = re.search(r"(?is)^select\s+(.*)$", normalized)
+    if not match:
+        return []
+    projection = match.group(1).strip()
+    if projection == "*":
+        return ["*"]
+    return [part.strip() for part in projection.split(",") if part.strip()]
+
+
+def projection_alias(expression: 'str', fallback_index: 'int') -> 'str':
+    alias_match = re.search(r"(?i)\bas\s+([a-zA-Z_][\w]*)$", expression)
+    if alias_match:
+        return alias_match.group(1)
+    bare = expression.split(".")[-1].strip()
+    if bare == expression and "(" in expression:
+        return f"_c{fallback_index}"
+    return bare
+
+
+def encode_cursor(offset: 'int', session_id: 'int | None' = None) -> 'str':
+    """Encode cursor with short keys: s=session_id, o=offset."""
+    payload: 'dict[str, int]' = {"o": offset}
+    if session_id is not None:
+        payload["s"] = session_id
+    return base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode("utf-8")).decode("utf-8")
+
+
+def decode_cursor(cursor: 'str | None') -> 'tuple[int, int | None]':
+    """Decode a cursor and return (offset, session_id)."""
+    if not cursor:
+        return 0, None
+    try:
+        payload = base64.urlsafe_b64decode(cursor.encode("utf-8")).decode("utf-8")
+        value = json.loads(payload)
+    except Exception as exc:
+        raise ValidationError(
+            "The cursor could not be parsed.",
+            suggestion="Use the `next_cursor` returned by the previous response.",
+        ) from exc
+    offset = value.get("o")
+    if not isinstance(offset, int) or offset < 0:
+        raise ValidationError(
+            "The cursor contains an invalid offset.",
+            suggestion="Use the `next_cursor` returned by the previous response.",
+        )
+    session_id = value.get("s")
+    return offset, session_id
+
+
+def read_sql_input(
+    sql_parts: 'list[str]',
+    *,
+    file_path: 'str | None',
+    use_stdin: 'bool',
+    stdin_text: 'str | None',
+) -> 'str':
+    provided_sources = sum(bool(item) for item in [sql_parts, file_path, use_stdin])
+    if provided_sources == 0:
+        raise ValidationError("Provide SQL via inline text, `--file`, or `--stdin`.")
+    if provided_sources > 1:
+        raise ValidationError("SQL input must come from exactly one source: inline text, `--file`, or `--stdin`.")
+
+    if sql_parts:
+        return " ".join(sql_parts).strip()
+    if file_path:
+        return Path(file_path).read_text(encoding="utf-8").strip()
+    if use_stdin:
+        content = (stdin_text or "").strip()
+        if not content:
+            raise ValidationError("No SQL was read from stdin.")
+        return content
+    raise ValidationError("Unable to resolve SQL input.")
+
+
+def short_json(value: 'Any') -> 'str':
+    return json.dumps(value, ensure_ascii=False, sort_keys=True)

maxc_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: maxc-cli
+Version: 0.1.0
+Summary: Agent-native MaxCompute CLI for external coding agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8,<3.13
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=5.4
+Requires-Dist: pyodps
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# maxc-cli
+
+`maxc-cli` 是一个面向外部 Agent 的 MaxCompute 工具层。它不是 Agent 本身，而是给 Codex、Claude Code、Cursor 或自研 Agent 调用的结构化 CLI。
+
+当前工作树以真实 MaxCompute 为目标。连接信息可以来自环境变量，也可以通过 `maxc auth login` 持久化到本地配置文件。缺少认证时，CLI 会返回结构化引导信息，不再回退到运行时 mock catalog。
+
+## 文档入口
+
+- `docs/design.md`
+  产品定位、命令体系和 skill/source 布局
+- `docs/implementation.md`
+  当前代码的真实行为和输出契约
+- `docs/product-positioning.md`
+  为什么当前应先把 `maxc-cli` 做成工具层
+- `docs/roadmap.md`
+  当前路线图和发布后续项
+- `skills/use-maxc-cli/`
+  仓库内 versioned 的 Codex skill source
+
+## 当前能力
+
+- 统一的 Agent-Native JSON envelope
+- `auth / session / query / job / meta / data / diff / cache / agent context`
+- `auth login`、`auth whoami`、`auth can-i`
+- `session set/show/unset`
+- `query cost`、`query explain`、分页 `--page-size` / `--cursor`
+- `meta search-columns`、richer `meta describe`、`meta latest-partition`、`meta freshness`
+- `meta lineage` 对真实 backend 明确返回 `supported=false` 占位契约
+- `data sample --partition --columns --rows`
+- `data profile --partition`
+- `diff schema`、`diff partition`、`diff data`
+- SQLite 本地缓存、结构化审计日志、语义元数据缓存
+- 仓库内置 `skills/use-maxc-cli/` skill source 与同步脚本 `scripts/sync_codex_skill.py`
+
+## 安装
+
+仓库内开发安装：
+
+```bash
+python -m pip install -e .
+```
+
+发布后安装：
+
+```bash
+python -m pip install maxc-cli
+```
+
+当前打包元数据支持 Python `3.6` 到 `3.12`。
+
+基础依赖已经包含：
+
+- `pyodps`
+- `PyYAML`
+- Python 3.6 下的 `dataclasses` backport
+
+按需依赖：
+
+- `pandas`
+  某些包含 TIMESTAMP-like 类型的结果集读取路径可能需要它，但它不是安装 `maxc-cli` 的直接前置依赖
+
+## Codex Skill
+
+仓库内 `skills/use-maxc-cli/` 是 canonical source。将它同步到本机 Codex skill 目录：
+
+```bash
+python scripts/sync_codex_skill.py
+```
+
+默认目标目录是：
+
+```text
+~/.codex/skills/use-maxc-cli
+```
+
+## 登录与 Bootstrap
+
+建议的最短接入路径：
+
+```bash
+maxc auth whoami --json
+maxc auth login --from-env --json
+maxc auth whoami --json
+maxc cache build --json
+maxc meta list-tables --json
+```
+
+如果当前 shell 已经有 MaxCompute 环境变量，可以直接持久化：
+
+```bash
+maxc auth login --from-env --json
+```
+
+显式传参登录：
+
+```bash
+maxc auth login \
+  --access-id "<access_key_id>" \
+  --secret-access-key "<access_key_secret>" \
+  --project "<project>" \
+  --endpoint "http://service.<region>.maxcompute.aliyun.com/api" \
+  --region "<region>" \
+  --json
+```
+
+`auth whoami --json` 的重点字段在 `data.identity`：
+
+- `authenticated`
+- `configured`
+- `validation_status`
+- `identity_source`
+- `project`
+
+如果 `authenticated=false`，继续查看 `data.auth_options` 获取推荐登录动作。
+
+默认配置发现顺序：
+
+```text
+~/.maxc/config.yaml
+./.maxc/config.yaml
+./.maxc.yaml
+./.maxc
+```
+
+项目和 schema 的会话覆盖保存在：
+
+```text
+~/.maxc/session_override.yaml
+```
+
+## 快速运行
+
+```bash
+maxc auth whoami --json
+maxc agent context --json
+maxc session show --json
+maxc cache build --json
+maxc meta list-tables --json
+maxc meta search-columns "id" --json
+maxc meta describe your_table --json
+maxc meta latest-partition your_table --json
+maxc meta freshness your_table --json
+maxc meta lineage your_table --json
+maxc data sample your_table --partition ds=2026-03-20 --columns id,ds --rows 5 --json
+maxc data profile your_table --partition ds=2026-03-20 --json
+maxc query "SELECT 1 AS one" --json
+maxc query cost "SELECT 1 AS one" --json
+maxc query explain "SELECT 1 AS one" --json
+maxc job submit "SELECT 1 AS one" --json
+maxc job wait job_xxx --stream
+maxc diff schema left_table right_table --json
+maxc diff partition left_table right_table --json
+maxc diff data left_table right_table --keys id --columns value_col --rows 100 --json
+maxc cache status --json
+maxc cache build-status --build-id build_xxx --json
+```
+
+## `cache build --json` 行为
+
+- `stdout` 只输出单个最终 JSON envelope
+- `stderr` 持续输出进度文本，避免慢构建期间完全静默
+- `--async --json` 会立即返回 `build_id`，随后用 `cache build-status --build-id <id> --json` 轮询
+
+## JSON 契约
+
+所有 `--json` 命令都返回 envelope：
+
+- `version`
+- `command`
+- `command_id`
+- `status`
+- `data`
+- `metadata`
+- `error`
+- `agent_hints`
+
+常用规范化 `data` 结构：
+
+- `auth whoami` -> `data.identity`
+- `auth can-i` -> `data.authorization`
+- `query` / `job wait` / `job result` -> `data.result` 和 `data.pagination`
+- `query cost` / `query explain` -> `data.analysis`
+- `meta describe` -> `data.table`
+- `meta search` / `meta search-columns` -> `data.search.matches`
+- `data sample` -> `data.sample`
+- `data profile` -> `data.profile`
+- `agent context` -> `data.context`
+
+## 当前限制
+
+- `meta lineage` 还没有接真实血缘 API；真实 backend 会明确返回 `supported=false`、`coverage=unsupported`
+- `auth can-i` 当前只支持表级 `SELECT` 预检
+- `auth login` 会把 AccessKey 明文写入本地 YAML；CLI 会尽量把文件权限收敛到 `0600`
+- 环境变量优先于配置文件；`session_override.yaml` 对 project/schema 的优先级高于两者
+- `meta list-tables` 是 cache-backed；冷启动时需要先执行 `cache build`
+- `diff data` 当前是 keyed snapshot compare：每侧最多读取 `--rows` 行，不是全表 exhaustive diff
+- 真实 backend 目前不提供统一 CU 口径成本，因此 `--cost-check` 在真实 backend 上不可用
+- 真实 backend 的 `query explain / query cost` 当前基于 `execute_sql_cost` 和结构化 query outline，不是完整优化器执行计划树
+- `--cursor` 当前是 CLI 侧 offset token，不是 MaxCompute 服务端游标

maxc_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+maxc_cli/__init__.py,sha256=gyVRundciHakyXcIdYpdgWapAbmk9MrRjJXvXgARn3o,74
+maxc_cli/__main__.py,sha256=P_XzMrNHOza38_dmqmIuv9POOCRxf4RiBC4-VoR6xBw,81
+maxc_cli/app.py,sha256=WDYmd9u8XCRaWXI7k68-8y-dwNpu8Uci0n7oV-rIk9E,134135
+maxc_cli/audit.py,sha256=D_p2CMnxCZAQZy0_UkvTCH61DLvLItWJnnTvE9sDSFE,516
+maxc_cli/auth_providers.py,sha256=gnf2vDtgcJXzab0CpJmbZDpAeJksaSuS4xGgRlMUhY8,17244
+maxc_cli/cache.py,sha256=6xq2Qv9UcKDU8ogpqitNB37DnBVzw_3P-mBa24PGNMw,28560
+maxc_cli/cli.py,sha256=Gyjp5uLyPCddAWDlRIzcJWgVmHMFTPzBuPle2CTnN3M,57414
+maxc_cli/config.py,sha256=ahjAAgyGFoVoWDN4vlu2DVauYnhP0NgLA2gTJN-ef-k,14338
+maxc_cli/exceptions.py,sha256=ZJr8NkEyiaB1WU3__VOxBtRkrNrKZh2Ymph6BS0RJXM,2177
+maxc_cli/helpers.py,sha256=t4xrxhg6CpBirCf-EWJBWw-tYSGgssql7duCZt51zEY,35960
+maxc_cli/models.py,sha256=lOR_KjKf3SDnbaDDtQVRVegcTlc8t_c3lGsbs_0QEIA,18517
+maxc_cli/output.py,sha256=kvWIB6cXDQSrkiC3g_66L7OeHqf7H4KT8kT4k3mZPv8,2418
+maxc_cli/store.py,sha256=b3QUkAHp_fV4m0ZCV2zx44KkNV3ZeOeVtx6V2Vy6VZw,4062
+maxc_cli/utils.py,sha256=jwub0dt6V_EpV455MzGjoueNz6u4FXYU6SayaIOp9uk,4517
+maxc_cli/backend/__init__.py,sha256=Tj1gfvBJlvneV6JO5I68bmnOSo3MC2Hq9hzur2hl9Gw,218
+maxc_cli/backend/auth.py,sha256=V9PLN6r0MpT3gE1na67TD8UUnlB3fnoQYYpt5DAN_Rw,5662
+maxc_cli/backend/data.py,sha256=yznGIucq1VJF3MKZB8IiZTIvCA8yAdAaFz9A3boRnWs,2940
+maxc_cli/backend/job.py,sha256=OFdhU8drsY8n7j1TARuOwo51Ut78aT4JHQ02vlRTSQQ,11280
+maxc_cli/backend/meta.py,sha256=INLtqpF9NUYyvHCBCYJknUN9b3br3HQ1Q0hTZI1oCr4,13702
+maxc_cli/backend/odps.py,sha256=OquxZihCYK10HeswvwrePRyk34r50M-vq2EkoLf9-Kg,4864
+maxc_cli/backend/query.py,sha256=QkyzxrLBtldL3is1WCB8ojkqHk-uuvBCVDjqSFPSOD0,5120
+maxc_cli-0.1.0.dist-info/METADATA,sha256=xMONx9lCkuW8D3hEsBKw2lqoxHjOfzf3f-ZluW2ZVaA,6682
+maxc_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+maxc_cli-0.1.0.dist-info/entry_points.txt,sha256=T-OEXGdDzvWEW_TMh8PpPidJv6nsB3xCU4JbiRXnfWM,48
+maxc_cli-0.1.0.dist-info/top_level.txt,sha256=2luw8czqtPh6ZOzQyGLxKHlTdao7sFY9RyhREBE6N8M,9
+maxc_cli-0.1.0.dist-info/RECORD,,

maxc_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maxc_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+maxc = maxc_cli.__main__:main

maxc_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maxc_cli