# Premium DM Cluster CLI Management

## Analysis

| Area | Impact | Verification |
| --- | --- | --- |
| `dataflow-service-ng/pkg/agent/types.go` | Add list response shape matching cluster-service-ng JSON payload | `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./pkg/agent/...` |
| `dataflow-service-ng/pkg/agent/dm.go` | Add `ListDMClusters` regional client method alongside existing `get/create/scale/delete` methods | `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./pkg/agent/...` |
| `dataflow-service-ng/internal/cmd/job_premium_dm_cluster.go` | Extend the CLI from `delete` only to `delete/get/list`, and emit JSON for read commands | `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./internal/cmd/...` |
| `dataflow-service-ng/internal/cmd/job_premium_dm_cluster_test.go` | Add command-level coverage for flag validation and JSON output | `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./internal/cmd/...` |
| `cluster-service-ng` discovery only | Confirm `ListDMClusters` server route, implementation, and tests already exist; no server code changes required | `rg -n "ListDMClusters" /Users/leon/WorkSpace/cloud/cluster-service-ng` |

### Dead Code / Cascade Check

- `cluster-service-ng` already exposes `GET /sharedPools/{shared_pool_id}/dmClusters` via `ListDMClusters`.
- The missing piece is only in `dataflow-service-ng`: its regional client has `get/create/scale/delete` for DM clusters, but not `list`.
- No protobuf, codegen, or server implementation changes are required for this increment.

### Symbols To Add / Change

- Add `agent.ListDMClustersResponse`
- Add `(*NGRegionalClient).ListDMClusters`
- Change `registerPremiumDMClusterJobFunc`
- Add `run_job premium_dm_cluster get`
- Add `run_job premium_dm_cluster list`
- Add command tests for `premium_dm_cluster`

## Execution Steps

1. Add the missing agent response shape and list client method.
   - Operation: extend `dataflow-service-ng/pkg/agent/types.go` with `ListDMClustersResponse`, then add `ListDMClusters(ctx, sharedPoolId)` in `dataflow-service-ng/pkg/agent/dm.go` using `GET /api/premium/v1/sharedPools/{sharedPoolId}/dmClusters`.
   - Verify: `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./pkg/agent/...`
   - Expected: agent package tests pass, including list response decoding.

2. Extend the Premium DM cluster CLI command tree.
   - Operation: update `dataflow-service-ng/internal/cmd/job_premium_dm_cluster.go` to register `delete`, `get`, and `list`; reuse the existing bootstrap path; build an ng regional client from the existing mgmt/agent config; print `get` and `list` responses as JSON to stdout.
   - Verify: `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go run ./cmd/dataflow run_job premium_dm_cluster --help`
   - Expected: help shows `delete`, `get`, and `list`.

3. Add command-level tests.
   - Operation: add unit tests for `get` and `list` command execution, stdout JSON output, and required-flag validation.
   - Verify: `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go test ./internal/cmd/...`
   - Expected: command tests pass and validate the new command surface.

4. Run final verification for the CLI surface.
   - Verify: `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go run ./cmd/dataflow run_job premium_dm_cluster get --help`
   - Expected: command usage is printed successfully.
   - Verify: `cd dataflow-service-ng && GOTOOLCHAIN=go1.25.7 go run ./cmd/dataflow run_job premium_dm_cluster list --help`
   - Expected: command usage is printed successfully.

## Risks

- The dataflow CLI reads through the mgmt proxy path; if the environment points at a cluster-service-ng version older than the repo state, `list` could fail at runtime despite compiling locally.
- Read commands now emit JSON to stdout; future callers should treat stdout as structured output rather than logs.
- `delete` remains behaviorally unchanged and intentionally does not emit structured JSON, to avoid changing existing automation unexpectedly.