maxc-cli 0.4.6__tar.gz → 0.4.7__tar.gz

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.4.6
+Version: 0.4.7
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -61,7 +61,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -128,12 +128,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/README.md

@@ -39,7 +39,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -106,12 +106,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/setup.py

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

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.6"
+__version__ = "0.4.7"

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/src/maxc_cli/output.py

@@ -84,6 +84,42 @@ def _stringify(value: Any) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _render_pending_md(envelope: Envelope) -> str:
+    """Render a pending/async envelope so the user sees status and how to wait."""
+    parts: list[str] = ["## Pending", ""]
+    parts.append("The query has not finished yet — it is still running asynchronously.")
+    parts.append("")
+
+    data = envelope.data or {}
+    metadata = envelope.metadata or {}
+    kv: dict[str, Any] = {}
+    job_id = data.get("job_id") or metadata.get("job_id")
+    if job_id:
+        kv["Job ID"] = job_id
+    if metadata.get("project"):
+        kv["Project"] = metadata["project"]
+    if metadata.get("wait_seconds") is not None:
+        kv["Waited"] = f"{metadata['wait_seconds']}s"
+    if metadata.get("logview"):
+        kv["Logview"] = metadata["logview"]
+    if kv:
+        parts.append(render_key_values(kv))
+        parts.append("")
+
+    parts.append("Wait for it to complete with:")
+    parts.append("")
+    hints = envelope.agent_hints
+    if hints is None or not hints.actions:
+        if job_id:
+            parts.append(f"- `maxc job wait {job_id} --json`")
+            parts.append(f"- `maxc job status {job_id} --json`")
+        else:
+            parts.append("- `maxc job wait <job_id> --json`")
+        parts.append("")
+        return "\n".join(parts)
+    return _append_agent_hints_md(parts, envelope)
+
+
 def render_markdown(envelope: Envelope) -> str:
     """Render an Envelope as human-readable markdown."""
     parts: list[str] = []
@@ -100,6 +136,10 @@ def render_markdown(envelope: Envelope) -> str:
         parts.append("")
         return _append_agent_hints_md(parts, envelope)
 
+    # --- Pending / async envelopes --------------------------------------
+    if envelope.status == "pending":
+        return _render_pending_md(envelope)
+
     command = envelope.command
     data = envelope.data
     metadata = envelope.metadata or {}
@@ -249,6 +289,16 @@ def render_brief(envelope: Envelope) -> str:
 
     data = envelope.data
 
+    # --- pending / async ------------------------------------------------
+    if envelope.status == "pending":
+        job_id = data.get("job_id") or (envelope.metadata or {}).get("job_id") or "?"
+        line = f"{command} | pending | job {job_id}"
+        if next_cmd:
+            line += f" | next: {next_cmd}"
+        elif job_id != "?":
+            line += f" | next: maxc job wait {job_id} --json"
+        return line
+
     # --- query ----------------------------------------------------------
     if envelope.command in {"query", "job.wait", "job.result"}:
         total = data.get("total_rows", "?")

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/src/maxc_cli/skills/SKILL.md

@@ -40,7 +40,7 @@ in SKILL.md alone.
 
 These are non-negotiable. See [references/red-lines.md](references/red-lines.md) for the full list including common mistakes, anti-patterns, and error recovery.
 
-1. **Always use `--json`** for machine work. Use `--format markdown` for user-facing output, `--format brief` in token-tight contexts. `--json` is shorthand for `--format json`. **`--format` is a top-level flag — it must come before the subcommand**: `{{cli}} --format markdown query "SELECT 1"` (✓), not `{{cli}} query "SELECT 1" --format markdown` (✗). `--json` may appear anywhere because each subcommand also accepts it.
+1. **Always use `--json`**. Agents should use JSON output consistently.
 2. **Never invent names** — table, schema, project, or endpoint. Verify with `meta` commands and `auth whoami`.
 3. **Default to `--project` for the user's target project.** The configured project (in `~/.maxc/config.yaml`) is the user's **dev project** — the data they actually want to query usually lives in a *different* project (often the corresponding production one). When the user mentions a table/project without specifying which environment, **ask first**, then pass `--project <name>` on every meta/data command and use `project.table` in SQL.
 4. **Project naming convention is a fixed pair:** `<name>_dev` is the dev project; the same `<name>` **without** the `_dev` suffix is its corresponding **production** project. Together they form one DataWorks workspace. They share metadata structure but hold different data and different permissions. See Dev vs Production Projects below.
@@ -125,11 +125,10 @@ Use `--project` to read metadata from the production project without switching s
 {{cli}} data sample my_table --project my_project --json
 ```
 
-When writing SQL, use `project.table` format to reference tables in another project:
+When querying production data from a dev project, use a fully qualified table name in SQL and pass the dev project explicitly:
 
-```sql
--- From dev project, query a production table
-SELECT * FROM my_project.my_table WHERE ds = '20260418' LIMIT 100
+```bash
+{{cli}} query "SELECT * FROM my_production_project.my_table WHERE ds = '20260418' LIMIT 100" --project my_dev_project
 ```
 
 Do NOT use bare table names (`FROM my_table`) when the target table lives in a different project — the query will fail with `TABLE_NOT_FOUND`.

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/src/maxc_cli/skills/references/command-patterns.md

@@ -140,7 +140,7 @@ Async pattern for long queries:
 
 ```bash
 # Step 1: submit
-{{cli}} query "SELECT * FROM my_schema.big_table WHERE ds = '20260418'" --wait 0 --json
+{{cli}} query "SELECT * FROM my_production_project.my_table WHERE ds = '20260418'" --project my_dev_project --wait 0 --json
 # Returns: { "status": "pending", "metadata": { "job_id": "<job_id>" } }
 
 # Step 2: extract metadata.job_id (e.g. 2026042011_abc123) and wait

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/src/maxc_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.4.6
+Version: 0.4.7
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -61,7 +61,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -128,12 +128,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.6 → maxc_cli-0.4.7}/tests/test_phase1_improvements.py

@@ -270,6 +270,34 @@ class TestRenderMarkdown:
         md = render_markdown(envelope)
         assert "maxc meta describe" in md
 
+    def test_query_pending_with_actions(self):
+        envelope = Envelope(
+            command="query",
+            status="pending",
+            data={"job_id": "job-42"},
+            metadata={"job_id": "job-42", "project": "demo", "wait_seconds": 10},
+            agent_hints=AgentHints(actions=[
+                SuggestedAction(id="job.wait", title="Wait for job", command="maxc job wait job-42 --json"),
+                SuggestedAction(id="job.status", title="Check status", command="maxc job status job-42 --json"),
+            ]),
+        )
+        md = render_markdown(envelope)
+        assert "Pending" in md
+        assert "(no rows)" not in md
+        assert "job-42" in md
+        assert "maxc job wait job-42 --json" in md
+
+    def test_query_pending_without_actions_falls_back(self):
+        envelope = Envelope(
+            command="query",
+            status="pending",
+            data={"job_id": "job-99"},
+            metadata={"job_id": "job-99"},
+        )
+        md = render_markdown(envelope)
+        assert "Pending" in md
+        assert "maxc job wait job-99 --json" in md
+
 
 class TestRenderBrief:
     def test_query_result(self):
@@ -286,6 +314,18 @@ class TestRenderBrief:
         assert "42" in brief
         assert len(brief) < 300
 
+    def test_query_pending_brief(self):
+        envelope = Envelope(
+            command="query",
+            status="pending",
+            data={"job_id": "job-7"},
+            metadata={"job_id": "job-7"},
+        )
+        brief = render_brief(envelope)
+        assert "pending" in brief
+        assert "job-7" in brief
+        assert "maxc job wait job-7 --json" in brief
+
     def test_meta_describe_brief(self):
         envelope = Envelope(
             command="meta.describe",