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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -59,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`（全局标志）。
 
@@ -69,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 检查
 

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

@@ -37,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`（全局标志）。
 
@@ -47,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 检查
 

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.3.0 → maxc_cli-0.3.1}/setup.py

@@ -9,7 +9,7 @@ README = ROOT / "README.md"
 
 setup(
     name="maxc-cli",
-    version="0.3.0",
+    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.3.0 → maxc_cli-0.3.1}/src/maxc_cli/__init__.py

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

{maxc_cli-0.3.0 → 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.0 → maxc_cli-0.3.1}/src/maxc_cli/_samples.py

@@ -6,7 +6,6 @@ quoting style they'd actually type.
 """
 from __future__ import annotations
 
-
 SAMPLES: dict[str, str] = {
     "__top__": (
         "maxc auth login\n"
@@ -147,14 +146,22 @@ SAMPLES: dict[str, str] = {
     "agent": (
         "maxc agent context\n"
         "maxc agent skill\n"
-        "maxc agent install-skill claude-code"
+        "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.install-skill": (
-        "maxc agent install-skill                  # defaults to claude-code\n"
-        "maxc agent install-skill cursor"
-    ),
+    "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_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]