@numa-tech/numa 1.12.11 → 1.13.1

package/dist/clusters/client.js

@@ -0,0 +1,207 @@
+import { resolveBackendUrl } from "../backend.js";
+import { ensureAccessToken, fetchWithKeycloakIdentity } from "../oauth.js";
+import { ClusterError } from "./errors.js";
+import { ClusterAdoptRequestSchema, ClusterApiErrorSchema, ClusterCandidateDecisionViewSchema, ClusterCandidatePageSchema, ClusterCandidateViewSchema, ClusterDetailSchema, ClusterDiscoveryRunViewSchema, ClusterIgnoreRequestSchema, ClusterLinkRequestSchema, ClusterObservationBatchReceiptSchema, ClusterObservationBatchRequestSchema, ClusterObservationPageSchema, ClusterObservationViewSchema, ClusterSourceCreateSchema, ClusterSourceListSchema, ClusterSourceUpdateSchema, ClusterSourceViewSchema, ClusterSummaryListSchema } from "./schemas.js";
+export const CLUSTER_CONTROL_PLANE_API_ROOT = "/api/v1/cluster-control-plane";
+export const CLUSTER_CONTROL_PLANE_CONTRACT_VERSION = "v1";
+function safeIdentifier(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 256 || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(trimmed)) {
+        throw new ClusterError(`${label} must be a stable platform identifier.`, "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return trimmed;
+}
+function safeIdempotencyKey(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 200 || !/^[A-Za-z0-9][A-Za-z0-9._:/+-]*$/u.test(trimmed)) {
+        throw new ClusterError("idempotency-key must be 1-200 safe opaque characters.", "CLUSTER_IDEMPOTENCY_INVALID");
+    }
+    return trimmed;
+}
+function positiveInteger(value, label, maximum) {
+    if (value == null)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new ClusterError(`${label} must be an integer between 1 and ${maximum}.`, "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return value;
+}
+function queryPath(path, values) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values)) {
+        if (value != null && value !== "")
+            query.set(key, String(value));
+    }
+    return query.size ? `${path}?${query.toString()}` : path;
+}
+async function responseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function requestIdFrom(response, body) {
+    if (body && typeof body === "object" && "requestId" in body && typeof body.requestId === "string")
+        return body.requestId;
+    return response.headers.get("x-request-id") ?? undefined;
+}
+function apiFailure(response, body) {
+    const parsed = ClusterApiErrorSchema.safeParse(body);
+    return new ClusterError(parsed.success && parsed.data.message
+        ? `Cluster Control Plane HTTP ${response.status}: ${parsed.data.message}`
+        : `Cluster Control Plane request failed with HTTP ${response.status}.`, parsed.success ? parsed.data.code ?? "CLUSTER_API_ERROR" : "CLUSTER_API_ERROR", response.status, requestIdFrom(response, body), parsed.success ? parsed.data.details : undefined);
+}
+function shouldRetryUnknown(error) {
+    if (error instanceof ClusterError) {
+        return [502, 503, 504].includes(error.status ?? 0) || /RESULT_UNKNOWN/u.test(error.code);
+    }
+    return error instanceof TypeError || (error instanceof Error && error.name === "AbortError");
+}
+export class ClusterControlPlaneClient {
+    config;
+    fetchImpl;
+    tokenProvider;
+    constructor(config, dependencies = {}) {
+        this.config = config;
+        this.fetchImpl = dependencies.fetch ?? fetch;
+        this.tokenProvider = dependencies.tokenProvider ?? ensureAccessToken;
+    }
+    async authenticatedFetch(path, init = {}) {
+        const method = String(init.method ?? "GET").toUpperCase();
+        const url = resolveBackendUrl(this.config, { method, path });
+        const headers = new Headers(init.headers);
+        headers.set("Accept", "application/json");
+        headers.set("X-Numa-Cluster-Contract", CLUSTER_CONTROL_PLANE_CONTRACT_VERSION);
+        if (init.body != null)
+            headers.set("Content-Type", "application/json");
+        return fetchWithKeycloakIdentity(this.config, url, () => ({ ...init, headers }), {
+            fetch: this.fetchImpl,
+            tokenProvider: this.tokenProvider
+        });
+    }
+    async json(path, schema, init = {}, expectedStatuses) {
+        const response = await this.authenticatedFetch(path, init);
+        const body = await responseBody(response);
+        if (!response.ok)
+            throw apiFailure(response, body);
+        if (expectedStatuses && !expectedStatuses.includes(response.status)) {
+            throw new ClusterError(`Cluster Control Plane returned HTTP ${response.status}; expected ${expectedStatuses.join(" or ")}.`, "CLUSTER_INVALID_RESPONSE", response.status, requestIdFrom(response, body));
+        }
+        const parsed = schema.safeParse(body);
+        if (!parsed.success) {
+            throw new ClusterError(`Cluster Control Plane returned an invalid response: ${parsed.error.message}`, "CLUSTER_INVALID_RESPONSE", response.status, requestIdFrom(response, body));
+        }
+        return parsed.data;
+    }
+    async mutation(path, schema, method, body, idempotencyKey, expectedStatuses) {
+        const key = safeIdempotencyKey(idempotencyKey);
+        const serialized = body == null ? undefined : JSON.stringify(body);
+        let lastError;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                return await this.json(path, schema, {
+                    method,
+                    headers: { "Idempotency-Key": key },
+                    ...(serialized == null ? {} : { body: serialized })
+                }, expectedStatuses);
+            }
+            catch (error) {
+                lastError = error;
+                if (!shouldRetryUnknown(error) || attempt === 1)
+                    break;
+            }
+        }
+        if (shouldRetryUnknown(lastError)) {
+            throw new ClusterError("Cluster mutation result is unknown. Retry the same command with the same Idempotency-Key and unchanged input.", "CLUSTER_RESULT_UNKNOWN", lastError instanceof ClusterError ? lastError.status : undefined, lastError instanceof ClusterError ? lastError.requestId : undefined);
+        }
+        throw lastError;
+    }
+    listClusters() {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/clusters`, ClusterSummaryListSchema);
+    }
+    getCluster(clusterKey) {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/clusters/${encodeURIComponent(safeIdentifier(clusterKey, "cluster-key"))}`, ClusterDetailSchema);
+    }
+    listSources() {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources`, ClusterSourceListSchema);
+    }
+    getSource(sourceKey) {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources/${encodeURIComponent(safeIdentifier(sourceKey, "source-key"))}`, ClusterSourceViewSchema);
+    }
+    listCandidates(options = {}) {
+        return this.json(queryPath(`${CLUSTER_CONTROL_PLANE_API_ROOT}/candidates`, {
+            status: options.status,
+            sourceKey: options.sourceKey,
+            page: positiveInteger(options.page, "page", 1_000_000),
+            size: positiveInteger(options.size, "size", 100)
+        }), ClusterCandidatePageSchema);
+    }
+    getCandidate(candidateKey) {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/candidates/${encodeURIComponent(safeIdentifier(candidateKey, "candidate-key"))}`, ClusterCandidateViewSchema);
+    }
+    listObservations(options = {}) {
+        return this.json(queryPath(`${CLUSTER_CONTROL_PLANE_API_ROOT}/observations`, {
+            sourceKey: options.sourceKey,
+            candidateKey: options.candidateKey,
+            page: positiveInteger(options.page, "page", 1_000_000),
+            size: positiveInteger(options.size, "size", 100)
+        }), ClusterObservationPageSchema);
+    }
+    getObservation(observationKey) {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/observations/${encodeURIComponent(safeIdentifier(observationKey, "observation-key"))}`, ClusterObservationViewSchema);
+    }
+    createSource(input, idempotencyKey) {
+        const parsed = ClusterSourceCreateSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Source input is invalid: ${parsed.error.message}`, "CLUSTER_CLI_INPUT_INVALID");
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources`, ClusterSourceViewSchema, "POST", parsed.data, idempotencyKey, [201]);
+    }
+    updateSource(sourceKey, input, idempotencyKey) {
+        const parsed = ClusterSourceUpdateSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Source update is invalid: ${parsed.error.message}`, "CLUSTER_CLI_INPUT_INVALID");
+        const source = encodeURIComponent(safeIdentifier(sourceKey, "source-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources/${source}`, ClusterSourceViewSchema, "PUT", parsed.data, idempotencyKey, [200]);
+    }
+    discoverSource(sourceKey, idempotencyKey) {
+        const source = encodeURIComponent(safeIdentifier(sourceKey, "source-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources/${source}/discover`, ClusterDiscoveryRunViewSchema, "POST", undefined, idempotencyKey, [202]);
+    }
+    getRun(runNo) {
+        return this.json(`${CLUSTER_CONTROL_PLANE_API_ROOT}/runs/${encodeURIComponent(safeIdentifier(runNo, "run-no"))}`, ClusterDiscoveryRunViewSchema);
+    }
+    submitObservations(sourceKey, input, idempotencyKey) {
+        const parsed = ClusterObservationBatchRequestSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Observation plan is invalid: ${parsed.error.message}`, "CLUSTER_PLAN_INVALID");
+        const source = encodeURIComponent(safeIdentifier(sourceKey, "source-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/sources/${source}/observations`, ClusterObservationBatchReceiptSchema, "POST", parsed.data, idempotencyKey, [202]);
+    }
+    adoptCandidate(candidateKey, input, idempotencyKey) {
+        const parsed = ClusterAdoptRequestSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Adopt input is invalid: ${parsed.error.message}`, "CLUSTER_CLI_INPUT_INVALID");
+        const candidate = encodeURIComponent(safeIdentifier(candidateKey, "candidate-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/candidates/${candidate}/adopt`, ClusterCandidateDecisionViewSchema, "POST", parsed.data, idempotencyKey, [200]);
+    }
+    linkCandidate(candidateKey, input, idempotencyKey) {
+        const parsed = ClusterLinkRequestSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Link input is invalid: ${parsed.error.message}`, "CLUSTER_CLI_INPUT_INVALID");
+        const candidate = encodeURIComponent(safeIdentifier(candidateKey, "candidate-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/candidates/${candidate}/link`, ClusterCandidateDecisionViewSchema, "POST", parsed.data, idempotencyKey, [200]);
+    }
+    ignoreCandidate(candidateKey, input, idempotencyKey) {
+        const parsed = ClusterIgnoreRequestSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ClusterError(`Ignore input is invalid: ${parsed.error.message}`, "CLUSTER_CLI_INPUT_INVALID");
+        const candidate = encodeURIComponent(safeIdentifier(candidateKey, "candidate-key"));
+        return this.mutation(`${CLUSTER_CONTROL_PLANE_API_ROOT}/candidates/${candidate}/ignore`, ClusterCandidateDecisionViewSchema, "POST", parsed.data, idempotencyKey, [200]);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/clusters/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/clusters/client.ts"],"names":[],"mappings":"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"}

package/dist/clusters/commands.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import { ClusterControlPlaneClient } from "./client.js";
+import { type KubeconfigDiscoveryOptions, type LocalKubeconfigDiscoveryPlan } from "./kubeconfig-discovery.js";
+export interface ClusterCommandDependencies {
+    clientFactory?: () => ClusterControlPlaneClient;
+    discoverKubeconfig?: (options: KubeconfigDiscoveryOptions) => Promise<LocalKubeconfigDiscoveryPlan>;
+    readPlan?: (path: string) => Promise<unknown>;
+}
+export declare function parseClusterIdentifier(value: string | undefined, label: string): string;
+export declare function parseClusterIdempotencyKey(value: string | undefined): string;
+export declare function registerClusterCommands(program: Command, dependencies?: ClusterCommandDependencies): void;

package/dist/clusters/commands.js

@@ -0,0 +1,373 @@
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { loadAppConfig } from "../app-config.js";
+import { loadConfig } from "../config.js";
+import { ClusterControlPlaneClient } from "./client.js";
+import { ClusterError, sanitizeClusterOutput } from "./errors.js";
+import { discoverKubeconfig, LocalKubeconfigDiscoveryPlanSchema, observationBatchFromPlan } from "./kubeconfig-discovery.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+const SAFE_KEY = /^[A-Za-z0-9][A-Za-z0-9._:/+-]*$/u;
+function addExamples(command, examples, notes = []) {
+    const noteSection = notes.length ? `\n说明:\n${notes.map((item) => `  - ${item}`).join("\n")}\n` : "";
+    return command.addHelpText("after", `${noteSection}\nExamples:\n${examples.map((item) => `  ${item}`).join("\n")}\n`);
+}
+function snakeCase(key) {
+    return key.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toLowerCase();
+}
+function stableOutput(value) {
+    const safe = sanitizeClusterOutput(value);
+    if (Array.isArray(safe))
+        return safe.map(stableOutput);
+    if (safe && typeof safe === "object") {
+        return Object.fromEntries(Object.entries(safe).map(([key, item]) => [snakeCase(key), stableOutput(item)]));
+    }
+    return safe;
+}
+async function jsonEnabled(command) {
+    const configured = await loadAppConfig();
+    return Boolean(command.optsWithGlobals().json || configured.output === "json");
+}
+async function output(command, payload, textValue) {
+    if (await jsonEnabled(command))
+        process.stdout.write(`${JSON.stringify(stableOutput(payload), null, 2)}\n`);
+    else
+        process.stdout.write(`${String(sanitizeClusterOutput(textValue))}\n`);
+}
+function outputPlan(plan) {
+    process.stdout.write(`${JSON.stringify(sanitizeClusterOutput(plan), null, 2)}\n`);
+}
+export function parseClusterIdentifier(value, label) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed || trimmed.length > 256 || !SAFE_ID.test(trimmed)) {
+        throw new ClusterError(`${label} must be a stable platform identifier.`, "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return trimmed;
+}
+export function parseClusterIdempotencyKey(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed || trimmed.length > 200 || !SAFE_KEY.test(trimmed)) {
+        throw new ClusterError("idempotency-key must be 1-200 safe opaque characters.", "CLUSTER_IDEMPOTENCY_INVALID");
+    }
+    return trimmed;
+}
+function requireYes(value) {
+    if (!value)
+        throw new ClusterError("Mutation requires --yes after reviewing the target and input.", "CLUSTER_CONFIRMATION_REQUIRED");
+}
+function integer(value, label, minimum = 0, maximum = 1_000_000) {
+    const parsed = Number(value);
+    if (value == null || !Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new ClusterError(`${label} must be an integer between ${minimum} and ${maximum}.`, "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return parsed;
+}
+function optionalPage(value, label, maximum) {
+    return value == null ? undefined : integer(value, label, 1, maximum);
+}
+function positiveId(value, label) {
+    const trimmed = value?.trim() ?? "";
+    if (!/^[1-9]\d*$/u.test(trimmed))
+        throw new ClusterError(`${label} must be a positive platform ID.`, "CLUSTER_CLI_INPUT_INVALID");
+    return trimmed;
+}
+function reason(value) {
+    const trimmed = value?.trim() ?? "";
+    if (trimmed.length < 5 || trimmed.length > 1000) {
+        throw new ClusterError("reason must contain 5-1000 characters.", "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return trimmed;
+}
+function regions(values) {
+    const normalized = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))].sort();
+    if (normalized.length > 100 || normalized.some((value) => !/^[a-z0-9-]{1,80}$/u.test(value))) {
+        throw new ClusterError("region values must be lowercase region codes.", "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return normalized;
+}
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+function sourceType(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "kubeconfig" || normalized === "kubeconfig-cli")
+        return "KUBECONFIG_CLI";
+    if (normalized === "ack" || normalized === "aliyun-ack-assume-role")
+        return "ALIYUN_ACK_ASSUME_ROLE";
+    throw new ClusterError("type must be kubeconfig or ack.", "CLUSTER_CLI_INPUT_INVALID");
+}
+function sourceLine(item) {
+    return `${String(item.sourceKey ?? "-")}\t${String(item.sourceType ?? "-")}\t${String(item.status ?? "-")}\tv${String(item.version ?? "-")}`;
+}
+function candidateLine(item) {
+    return `${String(item.candidateKey ?? "-")}\t${String(item.status ?? "-")}\t${String(item.matchKind ?? "-")}\t${String(item.matchedClusterKey ?? "-")}`;
+}
+function observationLine(item) {
+    return `${String(item.observationKey ?? "-")}\t${String(item.candidateKey ?? "-")}\t${String(item.provider ?? "-")}\t${String(item.disposition ?? "-")}`;
+}
+async function defaultReadPlan(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch {
+        throw new ClusterError("Discovery plan file could not be read.", "CLUSTER_PLAN_INVALID");
+    }
+    if (Buffer.byteLength(contents) > 2 * 1024 * 1024)
+        throw new ClusterError("Discovery plan file is too large.", "CLUSTER_PLAN_INVALID");
+    try {
+        return JSON.parse(contents);
+    }
+    catch {
+        throw new ClusterError("Discovery plan file is not valid JSON.", "CLUSTER_PLAN_INVALID");
+    }
+}
+function sourceUpdateBody(current, options) {
+    if (options.enable && options.disable)
+        throw new ClusterError("Choose only one of --enable or --disable.", "CLUSTER_CLI_INPUT_INVALID");
+    const expectedVersion = integer(options.expectedVersion, "expected-version");
+    if (current.version !== expectedVersion) {
+        throw new ClusterError("expected-version does not match the current source; review it before retrying.", "CLUSTER_SOURCE_VERSION_MISMATCH", 412);
+    }
+    const aliyunAccountId = options.aliyunAccountId == null ? current.aliyunAccountId ?? null : positiveId(options.aliyunAccountId, "aliyun-account-id");
+    const aliyunAssumeRoleId = options.aliyunAssumeRoleId == null ? current.aliyunAssumeRoleId ?? null : positiveId(options.aliyunAssumeRoleId, "aliyun-assume-role-id");
+    const selectedRegions = options.region == null ? current.regions : regions(options.region);
+    if (current.sourceType === "KUBECONFIG_CLI" && (aliyunAccountId != null || aliyunAssumeRoleId != null || selectedRegions.length)) {
+        throw new ClusterError("KUBECONFIG_CLI source cannot reference Alibaba Cloud identity or regions.", "CLUSTER_CLI_INPUT_INVALID");
+    }
+    if (current.sourceType === "ALIYUN_ACK_ASSUME_ROLE" && (aliyunAccountId == null || aliyunAssumeRoleId == null || !selectedRegions.length)) {
+        throw new ClusterError("ACK source requires account, assume Role, and at least one region.", "CLUSTER_CLI_INPUT_INVALID");
+    }
+    return {
+        displayName: options.displayName?.trim() || current.displayName,
+        aliyunAccountId,
+        aliyunAssumeRoleId,
+        regions: selectedRegions,
+        enabled: options.enable ? true : options.disable ? false : current.enabled,
+        expectedVersion
+    };
+}
+export function registerClusterCommands(program, dependencies = {}) {
+    const client = () => dependencies.clientFactory?.() ?? new ClusterControlPlaneClient(loadConfig());
+    const cluster = program.command("cluster")
+        .description("发现、核对并治理跨集群 Cluster Control Plane inventory")
+        .addHelpText("after", `
+安全边界:
+  kubeconfig discovery 仅在本机调用 kubectl 并输出脱敏 plan；不会上传 kubeconfig、endpoint、UID、CA、用户或凭据。
+  ACK source 只引用平台 accountId 和必选 assumeRoleId；CLI 不读取或传递 AK/SK。
+  所有写操作要求稳定 Idempotency-Key 和 --yes；结果未知时必须原键、原输入重试。
+`);
+    addExamples(cluster.command("list").description("列出受管集群")
+        .action(async (_options, command) => {
+        const result = await client().listClusters();
+        await output(command, { clusters: result, count: result.length }, result.map((item) => `${item.clusterKey}\t${item.status}\t${item.code}\t${item.name}`).join("\n") || "没有集群");
+    }), ["numa cluster list --json"]);
+    addExamples(cluster.command("read <cluster-key>").description("按 stable clusterKey 查看集群详情")
+        .action(async (clusterKey, _options, command) => {
+        const result = await client().getCluster(parseClusterIdentifier(clusterKey, "cluster-key"));
+        await output(command, result, `${result.cluster.clusterKey}\t${result.cluster.status}\t${result.cluster.name}`);
+    }), ["numa cluster read clu_0123456789abcdef0123456789abcdef --json"]);
+    addExamples(cluster.command("run <run-no>").description("查看 ACK discovery 运行状态")
+        .action(async (runNo, _options, command) => {
+        const result = await client().getRun(parseClusterIdentifier(runNo, "run-no"));
+        await output(command, result, `${result.runNo}\t${result.state}\t${result.sourceKey}`);
+    }), ["numa cluster run cdr_01 --json"]);
+    addExamples(cluster.command("sources [source-key]").description("列出 discovery sources，或查看一个 source")
+        .action(async (sourceKey, _options, command) => {
+        if (sourceKey) {
+            const result = await client().getSource(parseClusterIdentifier(sourceKey, "source-key"));
+            await output(command, result, sourceLine(result));
+        }
+        else {
+            const result = await client().listSources();
+            await output(command, { sources: result, count: result.length }, result.map(sourceLine).join("\n") || "没有 discovery source");
+        }
+    }), ["numa cluster sources --json", "numa cluster sources local-kubeconfig --json"]);
+    const candidates = cluster.command("candidates [candidate-key]").description("分页列出 candidates，或查看一个 candidate")
+        .option("--status <status>", "candidate 状态过滤")
+        .option("--source <source-key>", "sourceKey 过滤")
+        .option("--page <number>", "1-based 页码")
+        .option("--size <number>", "每页 1-100 条");
+    addExamples(candidates.action(async (candidateKey, options, command) => {
+        if (candidateKey) {
+            const result = await client().getCandidate(parseClusterIdentifier(candidateKey, "candidate-key"));
+            await output(command, result, candidateLine(result));
+        }
+        else {
+            const result = await client().listCandidates({
+                ...(options.status ? { status: options.status.trim().toUpperCase() } : {}),
+                ...(options.source ? { sourceKey: parseClusterIdentifier(options.source, "source") } : {}),
+                ...(options.page ? { page: optionalPage(options.page, "page", 1_000_000) } : {}),
+                ...(options.size ? { size: optionalPage(options.size, "size", 100) } : {})
+            });
+            await output(command, result, result.items.map(candidateLine).join("\n") || "没有 candidate");
+        }
+    }), ["numa cluster candidates --status pending --source local-kubeconfig --json"]);
+    const observations = cluster.command("observations [observation-key]").description("分页列出脱敏 observations，或查看一条 observation")
+        .option("--source <source-key>", "sourceKey 过滤")
+        .option("--candidate <candidate-key>", "candidateKey 过滤")
+        .option("--page <number>", "1-based 页码")
+        .option("--size <number>", "每页 1-100 条");
+    addExamples(observations.action(async (observationKey, options, command) => {
+        if (observationKey) {
+            const result = await client().getObservation(parseClusterIdentifier(observationKey, "observation-key"));
+            await output(command, result, observationLine(result));
+        }
+        else {
+            const result = await client().listObservations({
+                ...(options.source ? { sourceKey: parseClusterIdentifier(options.source, "source") } : {}),
+                ...(options.candidate ? { candidateKey: parseClusterIdentifier(options.candidate, "candidate") } : {}),
+                ...(options.page ? { page: optionalPage(options.page, "page", 1_000_000) } : {}),
+                ...(options.size ? { size: optionalPage(options.size, "size", 100) } : {})
+            });
+            await output(command, result, result.items.map(observationLine).join("\n") || "没有 observation");
+        }
+    }), ["numa cluster observations --source local-kubeconfig --json"]);
+    const source = cluster.command("source").description("管理受控 discovery source（ops-admin）");
+    const create = source.command("create").description("登记 kubeconfig CLI 或 ACK assume-role source")
+        .requiredOption("--source-key <key>", "stable source key")
+        .requiredOption("--type <kubeconfig|ack>", "source 类型")
+        .requiredOption("--display-name <name>", "显示名称")
+        .option("--aliyun-account-id <id>", "平台 Alibaba Cloud account ID")
+        .option("--aliyun-assume-role-id <id>", "平台 ACTIVE assume Role ID")
+        .option("--region <region>", "ACK region，可重复", collect)
+        .option("--disabled", "创建为 DISABLED")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认登记");
+    addExamples(create.action(async (options, command) => {
+        requireYes(options.yes);
+        const type = sourceType(options.type);
+        const selectedRegions = regions(options.region);
+        const input = {
+            sourceKey: parseClusterIdentifier(options.sourceKey, "source-key"),
+            sourceType: type,
+            displayName: options.displayName.trim(),
+            ...(options.aliyunAccountId ? { aliyunAccountId: positiveId(options.aliyunAccountId, "aliyun-account-id") } : {}),
+            ...(options.aliyunAssumeRoleId ? { aliyunAssumeRoleId: positiveId(options.aliyunAssumeRoleId, "aliyun-assume-role-id") } : {}),
+            regions: selectedRegions,
+            enabled: !options.disabled
+        };
+        const result = await client().createSource(input, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, sourceLine(result));
+    }), [
+        "numa cluster source create --source-key local-kubeconfig --type kubeconfig --display-name 'Local kubeconfig' --idempotency-key source-local-1 --yes --json",
+        "numa cluster source create --source-key ack-prod --type ack --display-name 'ACK production' --aliyun-account-id 7 --aliyun-assume-role-id 12 --region cn-shenzhen --idempotency-key source-ack-prod-1 --yes --json"
+    ]);
+    const update = source.command("update <source-key>").description("乐观锁更新 discovery source")
+        .requiredOption("--expected-version <number>", "当前 source version")
+        .option("--display-name <name>", "新显示名称")
+        .option("--aliyun-account-id <id>", "平台 Alibaba Cloud account ID")
+        .option("--aliyun-assume-role-id <id>", "平台 ACTIVE assume Role ID")
+        .option("--region <region>", "替换 ACK region 集合，可重复", collect)
+        .option("--enable", "启用 source")
+        .option("--disable", "禁用 source")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认更新");
+    addExamples(update.action(async (sourceKey, options, command) => {
+        requireYes(options.yes);
+        const stableSource = parseClusterIdentifier(sourceKey, "source-key");
+        const api = client();
+        const current = await api.getSource(stableSource);
+        const result = await api.updateSource(stableSource, sourceUpdateBody(current, options), parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, sourceLine(result));
+    }), ["numa cluster source update ack-prod --expected-version 2 --region cn-shenzhen --region cn-shanghai --idempotency-key source-ack-prod-v2 --yes --json"]);
+    const remoteDiscover = source.command("discover <source-key>").description("启动 ACK source 服务端发现运行")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认调用云只读发现");
+    addExamples(remoteDiscover.action(async (sourceKey, options, command) => {
+        requireYes(options.yes);
+        const stableSource = parseClusterIdentifier(sourceKey, "source-key");
+        const api = client();
+        const current = await api.getSource(stableSource);
+        if (current.sourceType !== "ALIYUN_ACK_ASSUME_ROLE") {
+            throw new ClusterError("source discover is only valid for ALIYUN_ACK_ASSUME_ROLE; use cluster discover kubeconfig locally.", "CLUSTER_CLI_INPUT_INVALID");
+        }
+        const result = await api.discoverSource(stableSource, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, `${result.runNo}\t${result.state}\t${result.sourceKey}`);
+    }), ["numa cluster source discover ack-prod --idempotency-key discover-ack-prod-20260822 --yes --json"]);
+    const candidate = cluster.command("candidate").description("治理 discovery candidate（ops-admin）");
+    const adopt = candidate.command("adopt <candidate-key>").description("把 candidate 登记成新集群")
+        .requiredOption("--code <code>", "新集群 code")
+        .requiredOption("--name <name>", "新集群名称")
+        .option("--description <text>", "说明")
+        .requiredOption("--expected-version <number>", "candidate version")
+        .requiredOption("--reason <text>", "5-1000 字符治理原因")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认 adopt");
+    addExamples(adopt.action(async (candidateKey, options, command) => {
+        requireYes(options.yes);
+        const result = await client().adoptCandidate(parseClusterIdentifier(candidateKey, "candidate-key"), {
+            code: options.code.trim(), name: options.name.trim(), ...(options.description ? { description: options.description.trim() } : {}),
+            expectedVersion: integer(options.expectedVersion, "expected-version"), reason: reason(options.reason)
+        }, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, `${result.action}\t${result.candidate.candidateKey}\t${result.cluster?.clusterKey ?? "-"}`);
+    }), ["numa cluster candidate adopt cand_01 --code ack-dev --name 'ACK dev' --expected-version 0 --reason 'Verified platform ownership' --idempotency-key adopt-cand-01 --yes --json"]);
+    const link = candidate.command("link <candidate-key>").description("把 candidate 关联到既有集群")
+        .requiredOption("--cluster <cluster-key>", "stable clusterKey")
+        .requiredOption("--expected-candidate-version <number>", "candidate version")
+        .requiredOption("--expected-cluster-version <number>", "cluster version")
+        .requiredOption("--reason <text>", "5-1000 字符治理原因")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认 link");
+    addExamples(link.action(async (candidateKey, options, command) => {
+        requireYes(options.yes);
+        const result = await client().linkCandidate(parseClusterIdentifier(candidateKey, "candidate-key"), {
+            clusterKey: parseClusterIdentifier(options.cluster, "cluster"),
+            expectedCandidateVersion: integer(options.expectedCandidateVersion, "expected-candidate-version"),
+            expectedClusterVersion: integer(options.expectedClusterVersion, "expected-cluster-version"),
+            reason: reason(options.reason)
+        }, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, `${result.action}\t${result.candidate.candidateKey}\t${result.cluster?.clusterKey ?? "-"}`);
+    }), ["numa cluster candidate link cand_01 --cluster clu_0123456789abcdef0123456789abcdef --expected-candidate-version 0 --expected-cluster-version 1 --reason 'Strong UID match verified' --idempotency-key link-cand-01 --yes --json"]);
+    const ignore = candidate.command("ignore <candidate-key>").description("忽略 candidate，并保留审计原因")
+        .requiredOption("--expected-version <number>", "candidate version")
+        .requiredOption("--reason <text>", "5-1000 字符治理原因")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键")
+        .option("--yes", "确认 ignore");
+    addExamples(ignore.action(async (candidateKey, options, command) => {
+        requireYes(options.yes);
+        const result = await client().ignoreCandidate(parseClusterIdentifier(candidateKey, "candidate-key"), {
+            expectedVersion: integer(options.expectedVersion, "expected-version"), reason: reason(options.reason)
+        }, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, `${result.action}\t${result.candidate.candidateKey}`);
+    }), ["numa cluster candidate ignore cand_01 --expected-version 0 --reason 'Temporary test cluster' --idempotency-key ignore-cand-01 --yes --json"]);
+    const discover = cluster.command("discover").description("本地发现生成 plan，并与显式批量提交分离");
+    const kubeconfig = discover.command("kubeconfig").description("只读遍历 kubeconfig context 并输出严格脱敏 JSON plan")
+        .option("--context <name>", "只发现一个 context")
+        .option("--kubeconfig <file>", "使用指定本地 kubeconfig；路径不会输出或上传")
+        .option("--timeout <seconds>", "每次 kubectl 短超时，默认 5，最大 30", "5");
+    addExamples(kubeconfig.action(async (options) => {
+        const plan = await (dependencies.discoverKubeconfig ?? discoverKubeconfig)({
+            ...(options.context ? { context: options.context } : {}),
+            ...(options.kubeconfig ? { kubeconfig: options.kubeconfig } : {}),
+            timeoutSeconds: integer(options.timeout, "timeout", 1, 30)
+        });
+        outputPlan(plan);
+    }), ["numa cluster discover kubeconfig --json > cluster-discovery.json", "numa cluster discover kubeconfig --context ack-dev --json"], [
+        "始终只输出脱敏 plan；不会调用 DevOps API，也不会输出 endpoint、kube-system UID、CA、user、token、cert、exec 或 auth-provider。"
+    ]);
+    const submit = discover.command("submit").description("把已审阅的本地 discovery plan 原子批量提交")
+        .requiredOption("--file <plan.json>", "cluster discover kubeconfig 输出的 JSON plan")
+        .requiredOption("--source <source-key>", "KUBECONFIG_CLI source")
+        .requiredOption("--idempotency-key <key>", "稳定幂等键；未知结果原值重试")
+        .option("--yes", "确认整批提交");
+    addExamples(submit.action(async (options, command) => {
+        requireYes(options.yes);
+        const sourceKey = parseClusterIdentifier(options.source, "source");
+        const raw = await (dependencies.readPlan ?? defaultReadPlan)(options.file);
+        const plan = LocalKubeconfigDiscoveryPlanSchema.safeParse(raw);
+        if (!plan.success)
+            throw new ClusterError(`Discovery plan is invalid: ${plan.error.message}`, "CLUSTER_PLAN_INVALID");
+        const api = client();
+        const sourceView = await api.getSource(sourceKey);
+        if (sourceView.sourceType !== "KUBECONFIG_CLI") {
+            throw new ClusterError("Local observations can only be submitted to a KUBECONFIG_CLI source.", "CLUSTER_CLI_INPUT_INVALID");
+        }
+        const batch = observationBatchFromPlan(plan.data, sourceKey);
+        const result = await api.submitObservations(sourceKey, batch, parseClusterIdempotencyKey(options.idempotencyKey));
+        await output(command, result, `${result.observationCount} observation(s)\t${result.candidateCount} candidate(s)\treplayed=${result.replayed}`);
+    }), ["numa cluster discover submit --file cluster-discovery.json --source local-kubeconfig --idempotency-key kube-observe-20260822-01 --yes --json"], [
+        "请求体只包含服务端 ObservationBatchRequest allow-list；整批最多 100 条并原子提交。",
+        "结果未知时必须复用同一文件、source 和 idempotency-key，CLI 会用相同 observation keys 重放。"
+    ]);
+}
+//# sourceMappingURL=commands.js.map