maxc-cli 0.2.5__tar.gz → 0.3.1__tar.gz

{maxc_cli-0.2.5 → maxc_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.2.5
+Version: 0.3.1
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -29,9 +29,12 @@ MaxCompute CLI — 不是 Agent，而是给 Agent 调用的结构化工具层。
 ```bash
 pip install maxc-cli
 
-# 认证
-maxc auth login --from-env --json          # 从环境变量
-maxc auth login --access-id ID --secret-access-key KEY --project PROJ --endpoint URL --json
+# 认证（推荐：交互式 Catalog Picker，无需手填 project）
+maxc auth login --access-id ID --access-key-secret KEY --json
+
+# 其他方式
+maxc auth login --from-env --json                                              # 从环境变量
+maxc auth login --access-id ID --access-key-secret KEY --project PROJ --endpoint URL --json  # CI / 脚本：显式 project
 
 # 确认就绪
 maxc auth whoami --json
@@ -56,7 +59,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
 | **diff** | `schema`, `partition`, `data` | 表结构/分区/数据对比 |
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
-| **agent** | `context`, `skill`, `install-skill` | Agent 集成与 SKILL 安装 |
+| **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
 所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
 
@@ -66,16 +69,16 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 
 SKILL HUB 安装 SKILL → Agent 读 SKILL.md → Agent 自己 `pip install maxc-cli`。
 
-### 方式 2：install-skill（内网兜底）
+### 方式 2：agent skill install（内网兜底）
 
 先 pip install，再一键注册到 Agent 平台：
 
 ```bash
 pip install maxc-cli
-maxc agent install-skill claude-code    # 或 cursor / windsurf / codex / qwen / qoder / qoderwork
+maxc agent skill install claude-code    # 或 cursor / windsurf / codex / qwen / qoder / qoderwork
 ```
 
-`install-skill` 从独立仓库 [maxcompute-cli-guidance](https://gitlab.alibaba-inc.com/aone-open-skill/maxcompute-cli-guidance) 获取 SKILL.md + references/ 并安装到目标平台目录。
+`agent skill install` 从独立仓库 [maxcompute-cli-guidance](https://gitlab.alibaba-inc.com/aone-open-skill/maxcompute-cli-guidance) 获取 SKILL.md + references/ 并安装到目标平台目录。
 
 ### preflight 检查
 
@@ -180,7 +183,9 @@ src/maxc_cli/
 ## 限制
 
 - **只读**：CLI 强制 SELECT-only，不支持 DDL/DML
-- **auth login**：AK/SK 明文存储于 `~/.maxc/config.yaml`（文件权限 0600）
+- **auth login**：AK/SK 明文存储于 `~/.maxc/config.yaml`（文件权限 0600）。
+  省略 `--project` 时通过 Catalog API 弹交互式 project picker（需 TTY，仅支持中国区 project）。
+  CI 用 `--no-picker`；想重选已保存的 project 用 `--reselect`；非中国区用 `--catalog-endpoint` 覆盖。
 - **list-tables 分页**：CLI 侧 offset token，非服务端游标
 - **diff data**：按主键快照对比，非全量 diff
 

{maxc_cli-0.2.5 → maxc_cli-0.3.1}/README.md

@@ -7,9 +7,12 @@ MaxCompute CLI — 不是 Agent，而是给 Agent 调用的结构化工具层。
 ```bash
 pip install maxc-cli
 
-# 认证
-maxc auth login --from-env --json          # 从环境变量
-maxc auth login --access-id ID --secret-access-key KEY --project PROJ --endpoint URL --json
+# 认证（推荐：交互式 Catalog Picker，无需手填 project）
+maxc auth login --access-id ID --access-key-secret KEY --json
+
+# 其他方式
+maxc auth login --from-env --json                                              # 从环境变量
+maxc auth login --access-id ID --access-key-secret KEY --project PROJ --endpoint URL --json  # CI / 脚本：显式 project
 
 # 确认就绪
 maxc auth whoami --json
@@ -34,7 +37,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
 | **diff** | `schema`, `partition`, `data` | 表结构/分区/数据对比 |
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
-| **agent** | `context`, `skill`, `install-skill` | Agent 集成与 SKILL 安装 |
+| **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
 所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
 
@@ -44,16 +47,16 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 
 SKILL HUB 安装 SKILL → Agent 读 SKILL.md → Agent 自己 `pip install maxc-cli`。
 
-### 方式 2：install-skill（内网兜底）
+### 方式 2：agent skill install（内网兜底）
 
 先 pip install，再一键注册到 Agent 平台：
 
 ```bash
 pip install maxc-cli
-maxc agent install-skill claude-code    # 或 cursor / windsurf / codex / qwen / qoder / qoderwork
+maxc agent skill install claude-code    # 或 cursor / windsurf / codex / qwen / qoder / qoderwork
 ```
 
-`install-skill` 从独立仓库 [maxcompute-cli-guidance](https://gitlab.alibaba-inc.com/aone-open-skill/maxcompute-cli-guidance) 获取 SKILL.md + references/ 并安装到目标平台目录。
+`agent skill install` 从独立仓库 [maxcompute-cli-guidance](https://gitlab.alibaba-inc.com/aone-open-skill/maxcompute-cli-guidance) 获取 SKILL.md + references/ 并安装到目标平台目录。
 
 ### preflight 检查
 
@@ -158,7 +161,9 @@ src/maxc_cli/
 ## 限制
 
 - **只读**：CLI 强制 SELECT-only，不支持 DDL/DML
-- **auth login**：AK/SK 明文存储于 `~/.maxc/config.yaml`（文件权限 0600）
+- **auth login**：AK/SK 明文存储于 `~/.maxc/config.yaml`（文件权限 0600）。
+  省略 `--project` 时通过 Catalog API 弹交互式 project picker（需 TTY，仅支持中国区 project）。
+  CI 用 `--no-picker`；想重选已保存的 project 用 `--reselect`；非中国区用 `--catalog-endpoint` 覆盖。
 - **list-tables 分页**：CLI 侧 offset token，非服务端游标
 - **diff data**：按主键快照对比，非全量 diff
 

maxc_cli-0.3.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py38"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+# E501 ignored for now: legacy codebase has 300+ long lines (mostly long SQL
+# strings, dense parameter lists, and docstrings). Tighten in a later sweep
+# once we've decided whether to wrap at the source or raise line-length.
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests put `pytestmark = pytest.mark.unit` before imports on purpose.
+"tests/*" = ["E402"]

{maxc_cli-0.2.5 → maxc_cli-0.3.1}/setup.py

@@ -9,7 +9,7 @@ README = ROOT / "README.md"
 
 setup(
     name="maxc-cli",
-    version="0.2.5",
+    version="0.3.1",
     description="Agent-native MaxCompute CLI for external coding agents",
     long_description=README.read_text(encoding="utf-8"),
     long_description_content_type="text/markdown",

{maxc_cli-0.2.5 → maxc_cli-0.3.1}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.5"
+__version__ = "0.3.1"

{maxc_cli-0.2.5 → maxc_cli-0.3.1}/src/maxc_cli/__main__.py

@@ -1,6 +1,5 @@
 
 from .cli import main
 
-
 if __name__ == "__main__":
     raise SystemExit(main())

maxc_cli-0.3.1/src/maxc_cli/_samples.py

@@ -0,0 +1,187 @@
+"""Per-command sample text for ``--help``. Keys are dotted command names.
+
+Style: 1-3 lines, concrete and copy-pasteable. Prefer realistic project names
+('my_proj') over placeholders ('PROJECT'). Wrap user-facing commands in the
+quoting style they'd actually type.
+"""
+from __future__ import annotations
+
+SAMPLES: dict[str, str] = {
+    "__top__": (
+        "maxc auth login\n"
+        'maxc query "SELECT 1"\n'
+        "maxc meta list-tables --project my_proj"
+    ),
+    # ── query ──────────────────────────────────────────────────────────────
+    "query": (
+        'maxc query "SELECT 1"\n'
+        'maxc query cost "SELECT * FROM big_table"\n'
+        "maxc query explain \"SELECT * FROM t WHERE dt='20260101'\""
+    ),
+    # ── auth ───────────────────────────────────────────────────────────────
+    "auth": "maxc auth login\nmaxc auth whoami --json",
+    "auth.login": (
+        "maxc auth login                         # interactive picker\n"
+        "maxc auth login --access-id AK --secret-access-key SK --no-picker"
+    ),
+    "auth.login-external": (
+        "maxc auth login-external --process-command 'curl -s https://my-sts/token'"
+    ),
+    "auth.whoami": "maxc auth whoami\nmaxc auth whoami --json",
+    "auth.can-i": "maxc auth can-i --table my_proj.my_table --operation SELECT",
+    # ── job ────────────────────────────────────────────────────────────────
+    "job": (
+        'maxc job submit "SELECT count(*) FROM my_table"\n'
+        "maxc job list --limit 20\n"
+        "maxc job status <job_id>"
+    ),
+    "job.submit": (
+        'maxc job submit "SELECT count(*) FROM my_table"\n'
+        'maxc job submit --file query.sql --project my_proj'
+    ),
+    "job.status": "maxc job status <job_id>\nmaxc job status <job_id> --json",
+    "job.wait": (
+        "maxc job wait <job_id>\n"
+        "maxc job wait <job_id> --timeout 600 --stream"
+    ),
+    "job.diagnose": "maxc job diagnose <job_id>\nmaxc job diagnose <job_id> --json",
+    "job.result": (
+        "maxc job result <job_id>\n"
+        "maxc job result <job_id> --max-rows 1000 --json"
+    ),
+    "job.cancel": "maxc job cancel <job_id>",
+    "job.list": "maxc job list\nmaxc job list --limit 50 --json",
+    # ── meta ───────────────────────────────────────────────────────────────
+    "meta": (
+        "maxc meta list-tables --project my_proj\n"
+        "maxc meta describe my_table\n"
+        "maxc meta search orders"
+    ),
+    "meta.list-tables": (
+        "maxc meta list-tables --project my_proj\n"
+        "maxc meta list-tables --schema default --limit 50 --json"
+    ),
+    "meta.describe": (
+        "maxc meta describe my_table\n"
+        "maxc meta describe my_proj.my_table --full --json"
+    ),
+    "meta.search": (
+        "maxc meta search orders\n"
+        "maxc meta search user --project my_proj --json"
+    ),
+    "meta.search-columns": (
+        "maxc meta search-columns user_id\n"
+        "maxc meta search-columns dt --project my_proj --json"
+    ),
+    "meta.latest-partition": (
+        "maxc meta latest-partition my_table\n"
+        "maxc meta latest-partition my_proj.my_table --json"
+    ),
+    "meta.freshness": (
+        "maxc meta freshness my_table\n"
+        "maxc meta freshness my_proj.my_table --json"
+    ),
+    "meta.partitions": (
+        "maxc meta partitions my_table\n"
+        "maxc meta partitions my_proj.my_table --limit 50 --json"
+    ),
+    "meta.list-projects": "maxc meta list-projects\nmaxc meta list-projects --json",
+    "meta.list-schemas": (
+        "maxc meta list-schemas\n"
+        "maxc meta list-schemas --project my_proj --json"
+    ),
+    # ── meta semantic ──────────────────────────────────────────────────────
+    "meta.semantic": (
+        "maxc meta semantic set my_table --desc 'Order facts'\n"
+        "maxc meta semantic get my_table\n"
+        "maxc meta semantic list-missing"
+    ),
+    "meta.semantic.set": (
+        "maxc meta semantic set my_table --desc 'Order facts'\n"
+        "maxc meta semantic set my_table --use-cases reporting analytics --sample-questions 'top users by revenue'"
+    ),
+    "meta.semantic.get": (
+        "maxc meta semantic get my_table\n"
+        "maxc meta semantic get my_table --json"
+    ),
+    "meta.semantic.list-missing": (
+        "maxc meta semantic list-missing\n"
+        "maxc meta semantic list-missing --json"
+    ),
+    # ── session ────────────────────────────────────────────────────────────
+    "session": (
+        "maxc session set --project my_proj\n"
+        "maxc session show\n"
+        "maxc session unset"
+    ),
+    "session.set": (
+        "maxc session set --project my_proj\n"
+        "maxc session set --project my_proj --schema default"
+    ),
+    "session.show": "maxc session show\nmaxc session show --json",
+    "session.unset": "maxc session unset",
+    # ── data ───────────────────────────────────────────────────────────────
+    "data": (
+        "maxc data sample my_table --rows 10\n"
+        "maxc data profile my_table\n"
+        "maxc data download my_table --output rows.csv"
+    ),
+    "data.sample": (
+        "maxc data sample my_table --rows 10\n"
+        "maxc data sample my_table --partition \"dt='20260101'\" --columns id,name"
+    ),
+    "data.profile": (
+        "maxc data profile my_table\n"
+        "maxc data profile my_table --partition \"dt='20260101'\" --json"
+    ),
+    "data.upload": (
+        "maxc data upload my_table --file rows.csv\n"
+        "maxc data upload my_table --file rows.tsv --delimiter $'\\t' --partition \"dt='20260101'\" --overwrite"
+    ),
+    "data.download": (
+        "maxc data download my_table --output rows.csv\n"
+        "maxc data download my_table --output rows.csv --columns id,name --limit 1000"
+    ),
+    # ── agent ──────────────────────────────────────────────────────────────
+    "agent": (
+        "maxc agent context\n"
+        "maxc agent skill\n"
+        "maxc agent skill install claude-code"
+    ),
+    "agent.context": "maxc agent context\nmaxc agent context --json",
+    "agent.skill": "maxc agent skill\nmaxc agent skill --json",
+    "agent.skill.install": (
+        "maxc agent skill install claude-code\n"
+        "maxc agent skill install cursor --invocation aliyun-maxc"
+    ),
+    "agent.skill.update": (
+        "maxc agent skill update cursor\n"
+        "maxc agent skill update --all"
+    ),
+    "agent.skill.uninstall": "maxc agent skill uninstall cursor",
+    "agent.skill.list": "maxc agent skill list --json",
+    "agent.skill.diff": "maxc agent skill diff cursor --unified",
+    "agent.skill.path": "maxc agent skill path cursor\nmaxc agent skill path --source",
+    # ── cache ──────────────────────────────────────────────────────────────
+    "cache": (
+        "maxc cache build --project my_proj\n"
+        "maxc cache status --project my_proj\n"
+        "maxc cache clear --project my_proj"
+    ),
+    "cache.build": (
+        "maxc cache build --project my_proj\n"
+        "maxc cache build --project my_proj --schema default --async"
+    ),
+    "cache.build-status": (
+        "maxc cache build-status --project my_proj\n"
+        "maxc cache build-status --project my_proj --build-id <id> --json"
+    ),
+    "cache.status": (
+        "maxc cache status --project my_proj\n"
+        "maxc cache status --project my_proj --schema default --json"
+    ),
+    "cache.clear": (
+        "maxc cache clear --project my_proj\n"
+        "maxc cache clear --project my_proj --schema default"
+    ),
+}

maxc_cli-0.3.1/src/maxc_cli/agent_platforms.py

@@ -0,0 +1,188 @@
+"""Agent platform registry — single source of truth for SKILL install targets.
+
+Each Platform declares where SKILL.md (and optional extra files) live for a
+specific agent product. The MaxCApp skill_install/update/uninstall/list/diff/path
+methods all consult REGISTRY here, so adding a new platform = one entry below
+(no code changes elsewhere).
+
+CRITICAL: install_root values must stay byte-equivalent to the legacy
+`_SKILL_PLATFORMS` table in `app.py:3375-3411` — see tests/test_agent_platforms.py
+::test_install_root_matches_legacy_paths.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+RenderFn = Callable[[Path, str, str], None]
+# (effective_install_root, cli, cli_module) -> None
+# Callee mkdir + write_text directly; returns nothing.
+# The first arg is the *effective* install root (after --dir override is applied
+# by the caller), not platform.install_root.
+# Args (cli, cli_module) are currently only consumed by SKILL.md template render;
+# extra_files with fixed-literal output (e.g., plugin.json) may ignore them.
+# Keep them in the signature so future extra_files using {{cli}} placeholders
+# don't need a protocol bump.
+
+
+@dataclass(frozen=True)
+class ExtraFile:
+    """Non-SKILL file co-installed with the skill (e.g., claude-plugin manifest).
+
+    `relative_path` is the discovery anchor for list/diff/uninstall — the
+    render_fn MUST write its content at `effective_install_root / relative_path`,
+    otherwise diff will report "file missing". Enforced by
+    test_render_claude_plugin_writes_declared_path.
+    """
+    relative_path: str
+    render_fn_name: str   # name of a callable in this module matching RenderFn
+
+
+@dataclass(frozen=True)
+class Platform:
+    name: str
+    install_root: Path
+    skill_subpath: str | None = None  # SKILL contents location relative to install_root;
+                                      # None = write into effective_install_root directly
+                                      # (claude-code uses this — SKILL.md and .claude-plugin/
+                                      # are siblings).
+    requires_dir: bool = True
+    extra_files: tuple[ExtraFile, ...] = ()
+    aliases: tuple[str, ...] = ()
+    deprecated_aliases: tuple[str, ...] = ()
+    next_step_hint: str = ""
+
+
+# Invocation map: cli front-end name → (cli, cli_module) substituted into
+# SKILL templates. Migrated here from app.py:3363-3372 so the registry is the
+# single source of truth.
+INVOCATIONS: dict[str, dict[str, str]] = {
+    "maxc": {
+        "cli": "maxc",
+        # `python3 -m` (not `python`) matches the legacy _SKILL_INVOCATIONS at
+        # app.py:3363-3372 byte-for-byte — changing this re-renders SKILL.md for
+        # every existing install and triggers a phantom `agent skill diff`.
+        "cli_module": "python3 -m maxc_cli",
+    },
+    "aliyun-maxc": {
+        "cli": "aliyun maxc",
+        "cli_module": "aliyun maxc",
+    },
+}
+
+
+def _claude_root() -> Path:
+    return Path.home() / ".claude" / "plugins" / "maxc-cli"
+
+
+def _codex_root() -> Path:
+    # Lazy — must re-read CODEX_HOME at call time, not module-import time,
+    # so the env var can be overridden in tests/CI.
+    return (
+        Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
+        / "skills"
+        / "maxcompute-cli-guidance"
+    )
+
+
+def _simple_root(dotdir: str) -> Path:
+    return Path.home() / dotdir / "skills" / "maxcompute-cli-guidance"
+
+
+def render_claude_plugin(install_dir: Path, cli: str, cli_module: str) -> None:
+    """Write `.claude-plugin/plugin.json` under `install_dir`.
+
+    Byte-equivalent to legacy literal at `app.py:3493-3499`. Do NOT reformat
+    via json.dumps(indent=…) — that re-flows whitespace and causes
+    `agent skill diff` to report a phantom delta against pre-existing installs.
+    """
+    meta_dir = install_dir / ".claude-plugin"
+    meta_dir.mkdir(parents=True, exist_ok=True)
+    (meta_dir / "plugin.json").write_text(
+        '{\n  "name": "maxc-cli",\n'
+        '  "description": "MaxCompute/ODPS CLI — query tables, view schema, '
+        'search metadata, execute SQL, check partitions, sample data, '
+        'track jobs. Install via: pip install maxc-cli",\n'
+        '  "author": { "name": "maxc-cli contributors" }\n}\n',
+        encoding="utf-8",
+    )
+
+
+def _build_registry() -> tuple[Platform, ...]:
+    """Build REGISTRY lazily so tests can monkeypatch HOME/CODEX_HOME + reload."""
+    return (
+        Platform(
+            name="claude-code",
+            install_root=_claude_root(),
+            skill_subpath=None,
+            extra_files=(ExtraFile(".claude-plugin/plugin.json", "render_claude_plugin"),),
+            next_step_hint="Run /reload-plugins in Claude Code to activate",
+        ),
+        Platform(name="cursor",    install_root=_simple_root(".cursor"),
+                 next_step_hint="Restart Cursor to activate"),
+        Platform(name="windsurf",  install_root=_simple_root(".windsurf"),
+                 next_step_hint="Restart Windsurf to activate"),
+        Platform(name="codex",     install_root=_codex_root(),
+                 next_step_hint="Restart Codex to activate"),
+        Platform(name="qwen",      install_root=_simple_root(".qwen"),
+                 next_step_hint="Restart Qwen to activate"),
+        Platform(name="qoder",     install_root=_simple_root(".qoder"),
+                 next_step_hint="Restart Qoder to activate"),
+        Platform(name="qoderwork", install_root=_simple_root(".qoderwork"),
+                 next_step_hint="Restart QoderWork to activate"),
+    )
+
+
+REGISTRY: tuple[Platform, ...] = _build_registry()
+
+
+def resolve(name_or_alias: str) -> Platform:
+    """Return the Platform matching name / alias / deprecated_alias.
+
+    Raises KeyError when no match. Caller is responsible for emitting a
+    stderr warning when the input matches `deprecated_aliases`.
+    """
+    for p in REGISTRY:
+        if name_or_alias == p.name:
+            return p
+        if name_or_alias in p.aliases:
+            return p
+        if name_or_alias in p.deprecated_aliases:
+            return p
+    raise KeyError(f"Unknown agent platform: {name_or_alias!r}")
+
+
+def all_platforms() -> tuple[Platform, ...]:
+    return REGISTRY
+
+
+def is_deprecated_alias(name: str) -> bool:
+    for p in REGISTRY:
+        if name in p.deprecated_aliases:
+            return True
+    return False
+
+
+def effective_target(platform: Platform, dir_override: Path | None) -> Path:
+    """Resolve where SKILL content for `platform` should be written.
+
+    effective_target = (--dir override OR platform.install_root) / (skill_subpath or "")
+    """
+    root = dir_override if dir_override is not None else platform.install_root
+    if platform.skill_subpath:
+        return root / platform.skill_subpath
+    return root
+
+
+def get_render_fn(name: str) -> RenderFn:
+    """Resolve a render_fn name (declared in ExtraFile) into the actual callable.
+
+    Kept here so caller can `getattr(agent_platforms, name)` without exposing the
+    module-internal naming convention to MaxCApp.
+    """
+    fn = globals().get(name)
+    if not callable(fn):
+        raise KeyError(f"render_fn not found in agent_platforms: {name!r}")
+    return fn  # type: ignore[return-value]