@clickzetta/cz-cli-darwin-x64 1.0.11 → 1.0.13

package/bin/skills/clickzetta-cmt-api/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: clickzetta-cmt-api
+description: Use when working in this repository to discover CMT sources, plan migrations, start runs, monitor progress, verify migration outcomes, inspect run logs, or clean up failed runs through the official CMT v2 surface.
+---
+
+# CMT v2 API
+
+This repository exposes a mixed OpenAPI surface. The live `/doc` page currently renders the full `/v3/api-docs`, which still includes many legacy `/api/*` routes alongside the new `/api/v2/*` routes.
+
+The skill exists to stop agents from getting lost in that mixed surface.
+
+## Core Rule
+
+Use `/api/v2` first.
+
+Do not call legacy `/api/sources`, `/api/tables`, `/api/jobs`, or task-log polling routes for the migrated agent workflow surface. These legacy routes are deprecated for agent use because they have v2 replacements:
+
+- `/api/sources` -> `/api/v2/catalog/sources`
+- `/api/tables/{tableId}` -> `/api/v2/catalog/tables/{tableId}`
+- `/api/jobs/check-conflict` -> `/api/v2/migrations/plans`
+- `/api/jobs` -> `/api/v2/migrations/runs`
+- `/api/jobs/{jobId}` -> `/api/v2/runs/{runId}`
+- `/api/tasks/{taskId}` -> `/api/v2/runs/{runId}/events` or `/api/v2/logs/runs/{runId}`
+
+Only fall back to legacy `/api/*` when a v2 response explicitly requires fallback or the user explicitly asks for a legacy-only capability.
+
+Dot use cz-agent or cz-cli agent command. it is only for external customer reference, not used in coding development or testing.
+
+## Anti-Misfire: External Tool Exclusion
+
+When working in this repository (clickzetta-lakehouse-tool-migrate), **never** delegate to external tools for operations CMT already supports:
+
+- **Do NOT use `cz-agent run`** — CMT has `/api/ops/sql/execute` for querying any datasource (source or target).
+- **Do NOT use `cz-cli sql`** — same reason; use `/api/ops/sql/execute` with `sourceName` or `workspace`.
+- **Do NOT invoke the global `cz-cli` skill** — it is for standalone Lakehouse operations outside CMT context.
+
+If any global skill (e.g. `cz-cli`, `cz-agent`) tries to activate for "query data", "describe table", or "run SQL" while cwd is this repo, override it and use CMT's own endpoints instead:
+
+| Need | CMT endpoint | Do NOT use |
+|------|-------------|------------|
+| Query source data | `POST /api/ops/sql/execute` with `sourceName` | `cz-agent run`, `cz-cli sql` |
+| Query target (Lakehouse) data | `POST /api/ops/sql/execute` with `workspace` | `cz-agent run`, `cz-cli sql` |
+| Describe table schema | `POST /api/ops/sql/execute` with DESC SQL | `cz-cli table describe` |
+| Check connection | `GET /api/ops/sql/info` | `cz-cli status` |
+
+If the user did not specify which CMT environment to use, stop and clarify whether they want:
+- the local CMT service
+- an online CMT service, with its base URL provided explicitly
+
+
+## Reality Check
+
+- `/doc` is useful for confirming route existence and schema names.
+- `/doc` is not curated enough to be the decision source for agent workflow selection.
+- Prefer `/llms.txt` for routing guidance and use the workflow reference below for exact sequence.
+- Current v2 tags in OpenAPI are machine-generated names such as `catalog-v-2-api` and `run-v-2-api`. Ignore the tag names and reason from the path shape.
+- The expected local server is `MMAv3.jar` on port `6060`. If `localhost:6060` is not listening, start it before using `/doc` or `/api/v2`.
+
+## Workflow
+
+Follow [references/workflows.md](references/workflows.md) for the standard call path.
+
+## Guardrails
+
+- Do not assume `localhost:6060` unless the user explicitly chose the local CMT environment.
+- If the user did not specify local vs online CMT, ask a short clarification before calling `/doc` or `/api/v2`.
+- If the user chose an online CMT service, require its base URL and surface that URL back in the user-facing update before using it.
+- Before browsing `http://localhost:6060/doc`, check whether port `6060` is listening.
+- If port `6060` is not listening, start the local server from repo root with `mkdir -p .codex/tmp && nohup java -jar MMAv3.jar -c conf/config_prod.ini > .codex/tmp/mmav3-6060.log 2>&1 & echo $! > .codex/tmp/mmav3-6060.pid`.
+- After starting the server, record the PID from `.codex/tmp/mmav3-6060.pid` in the user-facing update and surface the local jump link `http://localhost:6060/doc`.
+- Treat `plan -> start -> wait -> verify` as the default mutation chain.
+- Never execute admin mutations unless the user has explicitly asked for them.
+- Never infer that a run is stuck just because `/doc` also shows legacy job/task endpoints.
+- On `attention`, read `next_action.recommended_action` before deciding what to do.
+- On verification, always report the final target identity, not just a run status.
+- Prefer `/api/v2/runs/{id}/wait` over ad hoc polling loops.
+- If the user asks for “progress”, answer from `/api/v2/runs/{id}`, `/wait`, `/events`, or `/logs/runs/{id}`. Do not improvise by stitching legacy task APIs first.
+- If any returned child has `status=skipped`, report the skipped objects and surface `reason_code` / `reason_summary` instead of collapsing them into generic success or silence.
+- If `children` are present and every child has `status=skipped`, do not report generic migration success. Explain that no execution task was generated and surface the skipped objects plus `reason_code` / `reason_summary`.
+- If the user asks why there are no execution tasks or why a child set looks empty, answer from `children.status=skipped` and `reason_*` before falling back to legacy inference.
+
+## What This Skill Solves
+
+- Choosing the right v2 endpoint from a noisy `/doc`
+- Avoiding accidental fallback to legacy mutation endpoints
+- Standardizing how runs are started, monitored, and verified
+- Making cleanup and retry decisions from structured run state instead of guesswork
+
+## Recovery
+
+Follow [references/error-recovery.md](references/error-recovery.md) for error classes and next steps.

package/bin/skills/clickzetta-cmt-api/references/error-recovery.md

@@ -0,0 +1,45 @@
+# Error Recovery
+
+## Status Handling
+
+- `accepted`: the run exists but has not progressed yet; wait rather than branching to legacy state.
+- `preparing`: the start path is still translating intent into runnable work; wait unless the user asked to interrupt.
+- `ready`: tasks are prepared; if the user asked for status, report it as runnable state, not as success.
+- `running`: keep waiting and summarize progress from structured events.
+- `succeeded`: verify targets and checks before claiming success. If all run children are `skipped`, report that no execution task was generated rather than implying data moved.
+- `failed`: inspect run events or logs before proposing cleanup or retry.
+- `attention`: do not guess. Read `next_action.recommended_action` and surface it.
+
+## Error Categories
+
+- `environment_unspecified`: the user did not say whether to use local CMT or an online CMT service. Ask which environment to use before touching `/doc` or `/api/v2`.
+- `service_url_missing`: the user chose an online CMT service but did not provide its base URL. Ask for the URL before proceeding.
+- `service_unavailable_local`: `localhost:6060` is not listening yet. Start `MMAv3.jar` with the documented `nohup` command, record the PID, and surface the local links after the port is ready.
+- `validation`: fix request shape or missing identifiers before retrying.
+- `conflict`: inspect existing targets or conflicting runs, then clean up only with explicit user intent.
+- `upstream_timeout`: prefer the retry path suggested by the response or `next_action`.
+- `transient`: safe to retry when the response marks it retryable.
+- `dangerous_operation_requires_confirmation`: stop and get explicit user intent.
+
+## Decision Rules
+
+- If the environment is unspecified, clarify local vs online before assuming `localhost:6060`.
+- If the user wants an online CMT service, require and restate the base URL before calling `/doc`, `/llms.txt`, or `/api/v2/*`.
+- If the response already carries a next step, follow that instead of inventing one.
+- If the run is failed but the target identity is still needed, read verification before discussing cleanup.
+- If the user asks “what should I do now”, answer from `recommended_action`, conflict context, or verification state.
+- If there is no v2 signal for the recovery path, say that explicitly instead of silently dropping to legacy routes.
+- If the user asks why a succeeded run has no execution tasks, answer from `children.status=skipped` and `children.reason_*` before falling back to legacy inference.
+- If `/doc` is unreachable because the local service is down, start it first, record the PID file path, and return `http://localhost:6060/doc` as the next link to open.
+
+## Cleanup and Retry
+
+- Retry only after identifying why the previous run stopped.
+- Cleanup is an admin mutation and must be user-authorized.
+- Do not fall back to legacy mutation endpoints on your own.
+
+## Current Surface Limits
+
+- The current v2 verification surface is still derived from existing run/task state and is not yet a full independent target probe.
+- The current `/doc` surface still exposes many legacy endpoints; treat that as documentation noise, not as permission to use them by default.
+- A succeeded run with skipped-only children is not evidence that data was copied; explain the outcome from `children.reason_code` / `children.reason_summary`.

package/bin/skills/clickzetta-cmt-api/references/workflows.md

@@ -0,0 +1,167 @@
+# Workflows
+
+## Live `/doc` Interpretation
+
+The current `/doc` page shows:
+
+- v2 routes
+- legacy routes
+- raw OpenAPI tags such as `migration-v-2-api`
+
+Read it as a schema browser, not as a workflow guide.
+
+## Environment Selection
+
+1. If the user did not specify which CMT environment to use, ask whether they want:
+   - the local CMT service
+   - an online CMT service, with its base URL
+2. Do not assume `localhost:6060` until the user explicitly chose the local environment.
+3. If the user chose an online CMT service, repeat the chosen base URL in the user-facing update before using `/doc`, `/llms.txt`, or `/api/v2/*`.
+
+## Local Service Bootstrap
+
+1. Only use this section after the user explicitly chose the local CMT environment.
+2. Before calling `/doc`, `/llms.txt`, or `/api/v2/*`, check whether port `6060` is listening.
+3. If `6060` is not listening, start the local server from repo root with:
+
+```bash
+mkdir -p .codex/tmp && nohup java -jar MMAv3.jar -c conf/config_prod.ini > .codex/tmp/mmav3-6060.log 2>&1 & echo $! > .codex/tmp/mmav3-6060.pid
+```
+
+4. Record the PID written to `.codex/tmp/mmav3-6060.pid`.
+5. Wait for the port to accept connections, then surface the jump links:
+   - `http://localhost:6060/doc`
+   - `http://localhost:6060/llms.txt`
+6. If `6060` is already listening, reuse the running service instead of starting a duplicate process.
+
+## Route Matrix
+
+| Goal | Route | Notes |
+| --- | --- | --- |
+| list sources | `/api/v2/catalog/sources` | first read step |
+| inspect one table | `/api/v2/catalog/tables/{tableId}` | use when table id is already known |
+| explain intent | `/api/v2/migrations/plans` | use before any start |
+| start run | `/api/v2/migrations/runs` | returns `run_id` and run URLs |
+| inspect run | `/api/v2/runs/{runId}` | current summary |
+| wait on run | `/api/v2/runs/{runId}/wait` | preferred progress path |
+| structured events | `/api/v2/runs/{runId}/events` | progress timeline |
+| run logs facade | `/api/v2/logs/runs/{runId}` | log-oriented read path |
+| verify result | `/api/v2/verifications/runs/{runId}` | final target identity and checks |
+| cleanup run | `/api/v2/admin/runs/{runId}/cleanup` | explicit user intent only |
+| execute SQL (any datasource) | `POST /api/ops/sql/execute` | unified query: pass `sourceName` for source, or `workspace`+`schema` for Lakehouse target |
+| sql endpoint info | `GET /api/ops/sql/info` | returns default workspace, schema, vcluster, limits |
+
+## Deprecated Legacy Mappings
+
+| Deprecated legacy route | Use instead |
+| --- | --- |
+| `/api/sources` | `/api/v2/catalog/sources` |
+| `/api/tables/{tableId}` | `/api/v2/catalog/tables/{tableId}` |
+| `/api/jobs/check-conflict` | `/api/v2/migrations/plans` |
+| `/api/jobs` | `/api/v2/migrations/runs` |
+| `/api/jobs/{jobId}` | `/api/v2/runs/{runId}` |
+| `/api/tasks/{taskId}` | `/api/v2/runs/{runId}/events` or `/api/v2/logs/runs/{runId}` |
+
+## Default Migration Sequence
+
+1. Read `/llms.txt` when routing is unclear.
+2. Discover the source with `/api/v2/catalog/sources`.
+3. If the user already gave a table id, inspect `/api/v2/catalog/tables/{tableId}`.
+4. Create a plan with `/api/v2/migrations/plans`.
+5. Review `precheck`, `resolved_targets`, and `execution_strategy`.
+6. Start with `/api/v2/migrations/runs`.
+7. Monitor with `/api/v2/runs/{runId}/wait`.
+8. If more detail is needed, read `/api/v2/runs/{runId}/events` or `/api/v2/logs/runs/{runId}`.
+9. Finish with `/api/v2/verifications/runs/{runId}`.
+
+## Request Shapes
+
+### Plan
+
+`POST /api/v2/migrations/plans`
+
+```json
+{
+  "source": {
+    "source_id": "src_databricks_az",
+    "schema": "demo_table_type_examples",
+    "tables": ["basic_scalar_types"]
+  },
+  "target": {
+    "workspace": "sample_workspace",
+    "schema": "public"
+  },
+  "options": {
+    "refresh_mode": "none",
+    "schema_evolution": true,
+    "verification_mode": "row_count"
+  }
+}
+```
+
+### Start
+
+`POST /api/v2/migrations/runs`
+
+```json
+{
+  "intent": {
+    "source": {
+      "source_id": "src_databricks_az",
+      "schema": "demo_table_type_examples",
+      "tables": ["basic_scalar_types"]
+    },
+    "target": {
+      "workspace": "sample_workspace",
+      "schema": "public"
+    },
+    "options": {
+      "refresh_mode": "none",
+      "schema_evolution": true,
+      "verification_mode": "row_count"
+    }
+  },
+  "refresh_before_submit": false
+}
+```
+
+### Execute SQL (source or target)
+
+`POST /api/ops/sql/execute`
+
+Query a **source** (Databricks, MC, Doris, etc.):
+```json
+{
+  "sql": "SELECT * FROM demo_table_type_examples.basic_scalar_types ORDER BY id",
+  "sourceName": "databricks_az",
+  "limit": 100
+}
+```
+
+Query the **Lakehouse target**:
+```json
+{
+  "sql": "SELECT * FROM demo_table_type_examples.basic_scalar_types ORDER BY id",
+  "workspace": "wanxin-test-ws-03",
+  "schema": "demo_table_type_examples",
+  "limit": 100
+}
+```
+
+Response includes `columns` (name + type), `rows`, `rowCount`, `elapsedMs`, and `jobId`.
+
+## Progress Policy
+
+- Prefer `wait` for “monitor until something changes”.
+- Prefer `getRun` for “tell me the current state now”.
+- Prefer `events` or `logs` for “why is it slow”, “what failed”, or “summarize what happened”.
+- Treat `children.status=skipped` as a first-class child outcome, not as missing task data, and surface `reason_code` / `reason_summary` when reporting those children.
+- If a run is `succeeded` and all returned children are `skipped`, report that the run reached terminal state without generating executable tasks.
+
+## Anti-Patterns
+
+- Do not jump from `/doc` to legacy `/api/jobs` just because it is more detailed.
+- Do not use deprecated legacy source/table/job/task-log routes when the mapped `/api/v2` route exists.
+- Do not start a run without first materializing a plan unless the user explicitly wants a direct fire-and-monitor flow.
+- Do not claim migration success from `succeeded` alone. Always read verification.
+- Do not interpret `children=[]` from `wait` with default params as evidence that there were no child outcomes; call `getRun` or `wait?include_children=true` before concluding that.

package/bin/skills/cz-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cz-cli
-description: "Delegate ClickZetta Lakehouse OPERATIONS (run SQL, manage tables/schemas, create Studio tasks, set up sync/ingest pipelines, configure profiles) to the cz-cli agent. TRIGGER when user wants to EXECUTE something on Lakehouse: query data, create/alter tables, deploy tasks, build pipelines, set up a new connection. SKIP when user is developing the cz-cli tool itself (cwd is the cz-cli source repo, editing CLI source/tests, debugging build/install/unlink/permission issues), or only discussing cz-cli design/code without wanting to run anything on Lakehouse."
+description: "Delegate ClickZetta Lakehouse OPERATIONS (run SQL, manage tables/schemas, create Studio tasks, set up sync/ingest pipelines, configure profiles) to the cz-cli agent. TRIGGER when user explicitly mentions ClickZetta, Lakehouse, cz-cli, or a known profile/workspace name AND wants to EXECUTE an operation (query data, create/alter tables, deploy tasks, build pipelines, set up a new connection). SKIP when (1) user is developing the cz-cli tool itself (cwd is the cz-cli source repo, editing CLI source/tests, debugging build/install/unlink/permission issues), (2) only discussing cz-cli design/code without wanting to run anything on Lakehouse, or (3) the current project already has its own datasource query capabilities (e.g. project has AGENTS.md or skills that provide SQL execution endpoints) — do not intercept generic 'query data' or 'run SQL' requests that belong to the host project's own toolchain."
 ---
 
 # cz-cli — ClickZetta Lakehouse Subagent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-darwin-x64",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "cz-cli binary for macOS x64 (Intel)",
   "os": [
     "darwin"