maxc-cli 0.1.8__tar.gz → 0.1.9__tar.gz

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.1.8
+Version: 0.1.9
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/setup.py

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

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli/app.py

@@ -1884,10 +1884,6 @@ class MaxCApp:
                         f"Unable to access project `{project}`: {exc}",
                         suggestion="Verify the project name and that the current identity has access.",
                     ) from exc
-            else:
-                warnings.append(
-                    "Project override was saved without remote validation because no authenticated backend session is active."
-                )
             override["project"] = project
             changes.append(f"project set to `{project}`")
             # Warn if session override project differs from the project saved in auth config

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli/exceptions.py

@@ -70,6 +70,7 @@ class MaxCError(Exception):
         """Return default recovery steps based on error code."""
         _STEPS: 'dict[str, list[str]]' = {
             "PERMISSION_DENIED": [
+                "If the current project does not end with _dev, you likely need the dev workspace (personal accounts usually only have dev access): maxc session set --project <project>_dev",
                 "Check the table and operation with: maxc auth can-i --table <table> --operation SELECT --json",
                 "Verify your project access with: maxc auth whoami --json",
                 "Contact your project administrator for access.",

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli/helpers.py

@@ -997,6 +997,17 @@ def classify_sql_error(message: str) -> dict[str, Any]:
     return {"error_type": "unknown"}
 
 
+def _dev_workspace_hint(project: 'str | None') -> 'str':
+    """Return a hint about switching to the _dev workspace if the project is not a dev workspace."""
+    if project and not project.endswith("_dev"):
+        return (
+            f"Current project '{project}' is a production workspace. "
+            f"Personal accounts usually only have access to the dev workspace (_dev). "
+            f"Try switching: maxc session set --project {project}_dev"
+        )
+    return ""
+
+
 def _build_permission_error(
     message: 'str',
     context: 'str',
@@ -1004,37 +1015,44 @@ def _build_permission_error(
     table_name: 'str | None',
     schema_name: 'str | None',
 ) -> 'PermissionDeniedError':
-    """Build permission-denied errors with more precise suggestions."""
+    """Build permission-denied errors with more precise suggestions.
+
+    The original ODPS error (with RequestId, error code, etc.) is always
+    preserved as the error message for diagnostics. Context-specific
+    guidance goes into the suggestion field.
+    """
+    dev_hint = _dev_workspace_hint(project_name)
+
     if context == "list_projects" and project_name:
-        return PermissionDeniedError(
-            f"Failed to list projects: missing Read permission on project {project_name}.",
-            suggestion=f"Verify that your account has `odps:Read` on project {project_name}, or contact the project owner.",
-        )
+        suggestion = f"Verify that your account has `odps:Read` on project {project_name}, or contact the project owner."
+        if dev_hint:
+            suggestion = f"{dev_hint}\n{suggestion}"
+        return PermissionDeniedError(message, suggestion=suggestion)
 
     if context == "list_schemas":
         target = project_name or "the current project"
-        return PermissionDeniedError(
-            f"Failed to list schemas: missing Read permission on project {target}.",
-            suggestion=f"Verify that your account has `odps:Read` on project {target}.",
-        )
+        suggestion = f"Verify that your account has `odps:Read` on project {target}."
+        if dev_hint:
+            suggestion = f"{dev_hint}\n{suggestion}"
+        return PermissionDeniedError(message, suggestion=suggestion)
 
     if context == "get_project_info" and project_name:
-        return PermissionDeniedError(
-            f"Failed to read project info: missing Read permission on project {project_name}.",
-            suggestion=f"Verify that your account has `odps:Read` on project {project_name}.",
-        )
+        suggestion = f"Verify that your account has `odps:Read` on project {project_name}."
+        if dev_hint:
+            suggestion = f"{dev_hint}\n{suggestion}"
+        return PermissionDeniedError(message, suggestion=suggestion)
 
     if table_name:
-        return PermissionDeniedError(
-            f"Operation failed: missing required permission on table {table_name}.",
-            suggestion=f"Verify that your account has the required permission on table {table_name}, or contact the project owner.",
-        )
+        suggestion = f"Verify that your account has the required permission on table {table_name}, or contact the project owner."
+        if dev_hint:
+            suggestion = f"{dev_hint}\n{suggestion}"
+        return PermissionDeniedError(message, suggestion=suggestion)
 
     if project_name:
-        return PermissionDeniedError(
-            f"Operation failed: missing required permission on project {project_name}.",
-            suggestion=f"Verify that your account has the required permission on project {project_name}, or contact the project owner.",
-        )
+        suggestion = f"Verify that your account has the required permission on project {project_name}, or contact the project owner."
+        if dev_hint:
+            suggestion = f"{dev_hint}\n{suggestion}"
+        return PermissionDeniedError(message, suggestion=suggestion)
 
     return PermissionDeniedError(message)
 

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli/models.py

@@ -38,8 +38,6 @@ class AgentHints:
     def to_dict(self) -> 'dict[str, Any]':
         payload: 'dict[str, Any]' = {}
         if self.actions:
-            payload["actions"] = [a.to_dict() for a in self.actions]
-            payload["action_ids"] = [a.id for a in self.actions]
             payload["next_actions"] = [a.command for a in self.actions]
         if self.warnings:
             payload["warnings"] = self.warnings
@@ -64,7 +62,6 @@ class Envelope:
         payload = {
             "version": self.version,
             "command": command,
-            "command_id": self.command,
             "status": self.status,
             "data": data,
             "metadata": self.metadata,

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli/skills/SKILL.md

@@ -100,7 +100,7 @@ See [references/migrate-from-odpscmd.md](references/migrate-from-odpscmd.md) for
 - `agent skill` returns the SKILL.md path and metadata.
 - `agent install-skill <platform>` registers the skill with an Agent platform (claude-code, cursor, windsurf, codex, qwen, qoder, qoderwork). Idempotent; re-run after `pip install --upgrade` to update local skill files.
 - Use normalized `data` shapes: `auth whoami` → `data.identity`, `query`/`job result` → `data.result`, `meta describe` → `data.table`, `data sample` → `data.sample`.
-- Use `agent_hints.actions[]` for structured navigation. Each action has `id`, `title`, `command`. Use `actions[].id` for stable program logic. Do not execute `next_actions` strings directly — they may have broken shell quoting; construct commands yourself from the action `id` and context.
+- Use `agent_hints.next_actions[]` for suggested follow-up commands. Each entry is a ready-to-run CLI command string. Do not execute them blindly — verify the command makes sense for your current context first.
 - Before exploring an unfamiliar project, ask the user which schema/table they need — do not iterate all schemas.
 - When a query fails with `SQL_ERROR`, read `error.suggestion` before retrying. Do not retry the same SQL unchanged.
 - For partitioned tables, always determine the partition value via `meta latest-partition` or `meta partitions` before querying.
@@ -169,16 +169,16 @@ When `--wait N` is exceeded, `status` is `pending` with a `job_id` in metadata:
     "sql_executed": "SELECT ..."
   },
   "agent_hints": {
-    "actions": [
-      {"id": "job.wait", "command": "maxc job wait 2026... --json"},
-      {"id": "job.status", "command": "maxc job status 2026... --json"}
+    "next_actions": [
+      "maxc job wait 2026... --json",
+      "maxc job status 2026... --json"
     ],
     "insights": ["Query promoted to async after 10s."]
   }
 }
 ```
 
-Follow up with `job.wait` or `job.status` using the `job_id`.
+Follow up with `maxc job wait` or `maxc job status` using the `job_id`.
 
 ### DDL/DML with --force
 
@@ -212,6 +212,8 @@ Standard flow for answering data questions:
 - Column names with spaces or special characters must be backtick-escaped: `` `column name` ``.
 - When filtering by column values, first check actual values with `data sample` or a `SELECT DISTINCT` query — don't guess enum values.
 - For partitioned tables, always filter by partition column in WHERE (e.g. `WHERE ds = '20260415'`) to avoid full-table scans. Use `maxc meta partitions <table>` to discover available partitions.
+- When the user is in a `_dev` workspace and needs to access tables from another project, SQL must use the full 3-tier `project.schema.table` format (e.g. `other_project.my_schema.my_table`), because `_dev` workspaces can only see tables within their own space by default.
+- MaxCompute projects map to workspaces. Within the organization, workspaces are split into dev (`_dev` suffix) and production. Personal accounts usually lack production workspace permissions. If you hit a permission error, first check whether you need to switch to `<project>_dev`.
 - Never log, echo, or include AK/SK in output — even in error context.
 
 ## Partition Query Strategy
@@ -288,6 +290,8 @@ See [references/maxcompute-sql-notes.md](references/maxcompute-sql-notes.md) for
 | Assuming `meta describe` data is live | Cache source may be stale; check `metadata.source` field and `agent_hints.warnings` |
 | Querying partitioned table without partition filter, or hardcoding/guessing partition values | Always run `meta latest-partition` first; use the exact returned value in WHERE (see Partition Query Strategy) |
 | Assuming 2-tier naming (`project.table`) | Check if project uses 3-tier namespace with `meta list-schemas` |
+| Using a production project name (without `_dev` suffix) with a personal account | Switch to the dev workspace: `maxc session set --project <project>_dev` |
+| Using `schema.table` to access tables in another project from a `_dev` workspace | Use `project.schema.table` 3-tier format to specify the target project |
 
 ## Agent Anti-Patterns
 
@@ -311,7 +315,7 @@ When a command returns `status=failure`, inspect the `error.code` field to deter
 | `TABLE_NOT_FOUND` | Table does not exist in the schema | Check `error.did_you_mean`; search with `meta search <name> --json` |
 | `COLUMN_NOT_FOUND` | Column reference does not exist | Check `error.available` for valid columns; run `meta describe <table> --json` |
 | `WRITE_OPERATION_REQUIRES_FORCE` | Write operation blocked by read-only mode | Read-only is enforced by design; use `--force` only if explicitly authorized |
-| `PERMISSION_DENIED` | No access to the resource | Run `auth can-i --table <t> --operation SELECT --json` to verify; switch account if needed |
+| `PERMISSION_DENIED` | No access to the resource | If the current project does NOT end with `_dev`, personal accounts likely need the dev workspace: `maxc session set --project <project>_dev`. Then verify with `auth can-i --table <t> --operation SELECT --json` |
 | `SQL_ERROR` | SQL syntax or execution error | Fix the SQL; use `query explain` to validate syntax first |
 | `COST_LIMIT_EXCEEDED` | Query cost exceeds `--cost-check` threshold | Lower the scan scope (add partition filters, reduce columns), or raise the threshold |
 | `BACKEND_CONNECTION_ERROR` | Network or service unavailable | Retry after a delay; check endpoint with `auth whoami --json` |

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/src/maxc_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.1.8
+Version: 0.1.9
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/tests/test_agent_hints_and_cli.py

@@ -16,7 +16,7 @@ from maxc_cli.exceptions import ValidationError
 from maxc_cli.models import AgentHints, Envelope, action
 
 
-def test_agent_hints_render_executable_commands_with_action_ids() -> 'None':
+def test_agent_hints_render_executable_commands() -> 'None':
     envelope = Envelope(
         command="query.cost",
         status="success",
@@ -34,9 +34,8 @@ def test_agent_hints_render_executable_commands_with_action_ids() -> 'None':
     payload = envelope.to_dict()
 
     assert payload["command"] == "query cost"
-    assert payload["command_id"] == "query.cost"
+    # command_id removed in v0.1.6+
     assert payload["data"] == {"analysis": {"estimated_input_size_bytes": 0}}
-    assert payload["agent_hints"]["action_ids"] == ["query.explain", "query"]
     assert payload["agent_hints"]["next_actions"] == [
         "maxc query explain 'SELECT 1 AS one' --json",
         "maxc query 'SELECT 1 AS one' --json",
@@ -73,7 +72,6 @@ def test_agent_hints_infer_table_query_and_pagination_commands() -> 'None':
             "next_cursor": "eyJvIjoyMH0=",
         },
     }
-    assert payload["agent_hints"]["action_ids"] == ["query", "query.paginate", "meta.describe"]
     assert payload["agent_hints"]["next_actions"] == [
         "maxc query 'SELECT * FROM sales.orders LIMIT 20' --json",
         "maxc query 'SELECT * FROM sales.orders LIMIT 20' --cursor eyJvIjoyMH0= --json",
@@ -136,7 +134,7 @@ def test_query_alias_routes_to_query_cost() -> 'None':
     assert app.calls == [("cost", "SELECT 1 AS one", None)]
     payload = json.loads(stdout.getvalue())
     assert payload["command"] == "query cost"
-    assert payload["command_id"] == "query.cost"
+    # command_id removed in v0.1.6+
 
 
 def test_query_alias_and_mode_flag_cannot_be_combined() -> 'None':
@@ -257,7 +255,7 @@ def test_auth_whoami_without_credentials_returns_guidance(tmp_path: 'Path', monk
     payload = envelope.to_dict()
 
     assert payload["command"] == "auth whoami"
-    assert payload["command_id"] == "auth.whoami"
+    # command_id removed in v0.1.6+
     assert payload["data"]["identity"]["authenticated"] is False
     assert payload["data"]["identity"]["configured"] is False
     assert payload["data"]["auth_options"][0]["command"] == "auth login --from-env"
@@ -269,7 +267,6 @@ def test_meta_list_projects_hints_use_existing_commands(tmp_path: 'Path') -> 'No
     envelope = app.meta_list_projects()
     payload = envelope.to_dict()
 
-    assert payload["agent_hints"]["action_ids"] == ["session.set", "meta.list-schemas"]
     assert payload["agent_hints"]["next_actions"] == [
         "maxc session set --json",
         "maxc meta list-schemas --json",
@@ -319,7 +316,7 @@ def test_cache_build_json_handler_emits_single_envelope() -> 'None':
     assert app.calls == [(None, None, False, True)]
     payload = json.loads(stdout.getvalue())
     assert payload["command"] == "cache build"
-    assert payload["command_id"] == "cache.build"
+    # command_id removed in v0.1.6+
     assert payload["status"] == "success"
     stderr_text = args.stderr.getvalue()
     assert "Fetching table list..." in stderr_text

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/tests/test_agent_skill_commands_context.py

@@ -194,15 +194,15 @@ class TestQueryModeDeprecation:
         """--mode run should still work for backward compatibility."""
         config = _make_config(tmp_path)
         code, payload, _ = _run_cmd(config, ["query", "SELECT 1", "--mode", "run", "--json"])
-        # argparse errors give exit code 2; any other code means argparse accepted --mode
-        assert code != 2, "--mode should not cause argparse error"
+        # argparse errors produce no JSON envelope; a non-empty payload means argparse accepted --mode
+        assert payload, "--mode should not cause argparse error (expected JSON envelope)"
 
     def test_mode_cost_still_works(self, tmp_path):
         """--mode cost should still work and trigger deprecation warning."""
         config = _make_config(tmp_path)
         code, payload, _ = _run_cmd(config, ["query", "SELECT 1", "--mode", "cost", "--json"])
-        # Should not be an argparse error
-        assert code != 2, "--mode cost should not cause argparse error"
+        # argparse errors produce no JSON envelope; a non-empty payload means argparse accepted --mode
+        assert payload, "--mode cost should not cause argparse error (expected JSON envelope)"
 
     def test_mode_hidden_from_help(self, tmp_path):
         """--mode should be suppressed from --help output."""

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/tests/test_cli_mock.py

@@ -144,7 +144,6 @@ def test_auth_login_can_create_new_explicit_config_without_validation(
 
     assert code == 0
     assert payload["command"] == "auth login"
-    assert payload["command_id"] == "auth.login"
     assert payload["data"]["persistence"]["saved"] is True
     assert payload["data"]["persistence"]["validated"] is False
     assert payload["data"]["identity"]["identity_source"] == "config_file"
@@ -199,7 +198,6 @@ auth:
 
     assert code == 0
     assert payload["command"] == "auth whoami"
-    assert payload["command_id"] == "auth.whoami"
     identity = payload["data"]["identity"]
     assert identity["authenticated"] is True
     assert identity["configured"] is True
@@ -290,7 +288,7 @@ auth:
     assert identity["configured"] is True
     assert identity["validation_status"] == "failed"
     assert identity["identity_source"] == "config_file"
-    assert payload["agent_hints"]["action_ids"] == ["auth.login", "auth.login-external"]
+    assert "maxc auth login" in str(payload["agent_hints"]["next_actions"])
     assert any(
         "failed to resolve remote whoami endpoint" in warning
         for warning in payload["agent_hints"]["warnings"]
@@ -392,7 +390,6 @@ allowed_operations:
 
     assert code == 1
     assert payload["command"] == "cache status"
-    assert payload["command_id"] == "cache.status"
     assert payload["status"] == "failure"
     assert payload["error"]["code"] == "VALIDATION_ERROR"
 
@@ -422,7 +419,6 @@ allowed_operations:
 
     assert code == 1
     assert payload["command"] == "session set"
-    assert payload["command_id"] == "session.set"
     assert payload["status"] == "failure"
     assert payload["error"]["code"] == "VALIDATION_ERROR"
 

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/tests/test_phase1_improvements.py

@@ -75,7 +75,7 @@ class TestActionFactory:
 
 
 class TestAgentHintsWithActions:
-    def test_serialization_derives_next_actions_and_action_ids(self):
+    def test_serialization_derives_next_actions(self):
         hints = AgentHints(actions=[
             SuggestedAction(
                 id="meta.describe",
@@ -89,13 +89,10 @@ class TestAgentHintsWithActions:
             ),
         ])
         d = hints.to_dict()
-        assert d["action_ids"] == ["meta.describe", "data.sample"]
         assert d["next_actions"] == [
             "maxc meta describe schools --json",
             "maxc data sample schools --json",
         ]
-        assert len(d["actions"]) == 2
-        assert d["actions"][0]["id"] == "meta.describe"
 
     def test_envelope_renders_actions_through_agent_hints(self):
         envelope = Envelope(
@@ -115,8 +112,7 @@ class TestAgentHintsWithActions:
         )
         payload = envelope.to_dict()
         hints = payload["agent_hints"]
-        assert "actions" in hints
-        assert hints["action_ids"] == ["meta.describe"]
+        assert "next_actions" in hints
         assert hints["next_actions"] == ["maxc meta describe <table_name> --json"]
 
 
@@ -415,24 +411,17 @@ class TestEnhancedClassifySqlError:
 
 
 class TestConsistency:
-    """Verify action_ids, actions[].id, command_id, and next_actions are consistent."""
+    """Verify next_actions and command formatting are consistent."""
 
-    def test_action_ids_match_actions(self):
+    def test_next_actions_are_command_strings(self):
         hints = AgentHints(actions=[
             action("meta.describe", data={"table_name": "t"}),
             action("data.sample", data={"table_name": "t"}),
         ])
         d = hints.to_dict()
-        assert d["action_ids"] == [a["id"] for a in d["actions"]]
+        assert all(isinstance(s, str) for s in d["next_actions"])
 
-    def test_next_actions_match_commands(self):
-        hints = AgentHints(actions=[
-            action("meta.describe", data={"table_name": "t"}),
-        ])
-        d = hints.to_dict()
-        assert d["next_actions"] == [a["command"] for a in d["actions"]]
-
-    def test_command_id_uses_dot_notation(self):
+    def test_command_uses_space_notation(self):
         envelope = Envelope(
             command="meta.describe",
             status="success",
@@ -440,33 +429,11 @@ class TestConsistency:
             metadata={},
         )
         payload = envelope.to_dict()
-        assert payload["command_id"] == "meta.describe"
         assert payload["command"] == "meta describe"
 
-    def test_command_id_consistent_with_action_vocabulary(self):
-        """command_id and action IDs should use same vocabulary."""
-        envelope = Envelope(
-            command="query.cost",
-            status="success",
-            data={},
-            metadata={"project": "p"},
-            agent_hints=AgentHints(actions=[
-                action("query.explain"),
-                action("query"),
-            ]),
-        )
-        payload = envelope.to_dict()
-        # command_id is dot notation
-        assert payload["command_id"] == "query.cost"
-        # action_ids are also dot notation
-        for aid in payload["agent_hints"]["action_ids"]:
-            assert "." in aid or aid in {"query"}  # single-word commands are ok
-
-    def test_empty_actions_produces_no_hints_keys(self):
+    def test_empty_actions_produces_no_next_actions(self):
         hints = AgentHints(actions=[], warnings=["test"])
         d = hints.to_dict()
-        assert "actions" not in d
-        assert "action_ids" not in d
         assert "next_actions" not in d
         assert d["warnings"] == ["test"]
 

{maxc_cli-0.1.8 → maxc_cli-0.1.9}/tests/test_setting_parser.py

@@ -176,36 +176,21 @@ def test_translate_odps_error_type_error_not_readonly():
 
 
 def test_cli_readonly_error_has_agent_hints():
-    """Verify that READ_ONLY_VIOLATION maps to agent_hints with --force mention."""
+    """Verify that client-side write detection returns WRITE_OPERATION_REQUIRES_FORCE with hints."""
     import io
     import json
-    from unittest.mock import patch, MagicMock
 
     from maxc_cli.cli import run
 
-    # Simulate a readonly error from the backend
-    from maxc_cli.exceptions import ReadOnlyError
-
-    mock_app = MagicMock()
-    mock_app.query.side_effect = ReadOnlyError(
-        "invalid statement in readonly mode",
-        suggestion="Use odpscmd for write operations.",
-    )
-
     stdout = io.StringIO()
 
-    with patch("maxc_cli.cli.MaxCApp", return_value=mock_app):
-        exit_code = run(
-            ["query", "CREATE TABLE t (id BIGINT)", "--json"],
-            stdout=stdout,
-        )
+    exit_code = run(
+        ["query", "CREATE TABLE t (id BIGINT)", "--json"],
+        stdout=stdout,
+    )
 
     assert exit_code != 0
     output = json.loads(stdout.getvalue())
-    assert output["error"]["code"] == "READ_ONLY_VIOLATION"
-    hints = output.get("agent_hints", {})
-    # READ_ONLY_VIOLATION hints should contain a warning about server-side read-only
-    warnings = hints.get("warnings", [])
-    assert any("read-only" in w.lower() or "readonly" in w.lower() for w in warnings)
-    # Should also have structured actions
-    assert "actions" in hints
+    assert output["error"]["code"] == "WRITE_OPERATION_REQUIRES_FORCE"
+    assert output["error"]["recoverable"] is True
+    assert "--force" in output["error"].get("suggestion", "")