@numa-tech/numa 1.12.11 → 1.13.1

package/dist/clusters/schemas.js

@@ -0,0 +1,201 @@
+import { z } from "zod";
+const NonEmptyString = z.string().trim().min(1);
+const OptionalString = NonEmptyString.nullable().optional();
+const PositiveId = z.union([
+    z.string().trim().regex(/^[1-9]\d*$/u),
+    z.number().int().positive()
+]).transform(String);
+const Sha256 = z.string().regex(/^[0-9a-f]{64}$/u);
+export const ClusterSourceTypeSchema = z.enum(["KUBECONFIG_CLI", "ALIYUN_ACK_ASSUME_ROLE"]);
+export const ClusterSourceStatusSchema = z.enum(["ACTIVE", "DISABLED", "ERROR"]);
+export const ClusterCandidateStatusSchema = z.enum(["PENDING", "MATCHED", "AMBIGUOUS", "ADOPTED", "LINKED", "IGNORED"]);
+export const ClusterGovernanceActionSchema = z.enum(["ADOPT", "LINK", "IGNORE"]);
+export const ClusterSummarySchema = z.object({
+    id: PositiveId.optional(),
+    clusterKey: NonEmptyString,
+    code: NonEmptyString,
+    name: NonEmptyString,
+    provider: NonEmptyString,
+    providerClusterId: OptionalString,
+    region: OptionalString,
+    status: NonEmptyString,
+    identityStatus: NonEmptyString,
+    endpointFingerprintPrefix: OptionalString,
+    lastObservedAt: OptionalString,
+    version: z.number().int().nonnegative()
+});
+export const ClusterDetailSchema = z.object({
+    cluster: ClusterSummarySchema,
+    description: OptionalString,
+    fingerprintKinds: z.array(NonEmptyString).default([]),
+    linkedCandidateKeys: z.array(NonEmptyString).default([])
+});
+export const ClusterSourceViewSchema = z.object({
+    id: PositiveId.optional(),
+    sourceKey: NonEmptyString,
+    sourceType: ClusterSourceTypeSchema,
+    displayName: NonEmptyString,
+    aliyunAccountId: PositiveId.nullable().optional(),
+    aliyunAssumeRoleId: PositiveId.nullable().optional(),
+    regions: z.array(NonEmptyString).default([]),
+    enabled: z.boolean(),
+    status: ClusterSourceStatusSchema,
+    lastObservedAt: OptionalString,
+    observationCount: z.number().int().nonnegative(),
+    lastErrorCode: OptionalString,
+    lastErrorMessage: OptionalString,
+    version: z.number().int().nonnegative()
+});
+export const FingerprintEvidenceSchema = z.object({
+    kind: NonEmptyString,
+    fingerprintPrefix: NonEmptyString,
+    strength: NonEmptyString,
+    matched: z.boolean()
+});
+export const ClusterObservationViewSchema = z.object({
+    observationKey: NonEmptyString,
+    sourceKey: NonEmptyString,
+    candidateKey: NonEmptyString,
+    observedName: OptionalString,
+    provider: NonEmptyString,
+    providerClusterId: OptionalString,
+    region: OptionalString,
+    kubernetesVersion: OptionalString,
+    evidence: z.array(FingerprintEvidenceSchema).default([]),
+    evidenceSource: z.enum(["KUBECONFIG_CLI", "ACK_API"]),
+    observedAt: OptionalString,
+    receivedAt: OptionalString,
+    disposition: OptionalString
+});
+export const ClusterCandidateViewSchema = z.object({
+    candidateKey: NonEmptyString,
+    sourceKey: NonEmptyString,
+    status: ClusterCandidateStatusSchema,
+    matchKind: NonEmptyString,
+    matchedClusterKey: OptionalString,
+    observedName: OptionalString,
+    provider: NonEmptyString,
+    providerClusterId: OptionalString,
+    region: OptionalString,
+    kubernetesVersion: OptionalString,
+    evidence: z.array(FingerprintEvidenceSchema).default([]),
+    firstObservedAt: OptionalString,
+    lastObservedAt: OptionalString,
+    observationCount: z.number().int().nonnegative(),
+    resolutionReason: OptionalString,
+    reviewedBy: OptionalString,
+    reviewedAt: OptionalString,
+    version: z.number().int().nonnegative()
+});
+export const ClusterSourceCreateSchema = z.object({
+    sourceKey: z.string().trim().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/u),
+    sourceType: ClusterSourceTypeSchema,
+    displayName: z.string().trim().min(1).max(200),
+    aliyunAccountId: PositiveId.nullable().optional(),
+    aliyunAssumeRoleId: PositiveId.nullable().optional(),
+    regions: z.array(z.string().regex(/^[a-z0-9-]{1,80}$/u)).max(100),
+    enabled: z.boolean().optional()
+}).strict().superRefine((value, context) => {
+    if (value.sourceType === "KUBECONFIG_CLI") {
+        if (value.aliyunAccountId != null || value.aliyunAssumeRoleId != null || value.regions.length) {
+            context.addIssue({ code: "custom", message: "KUBECONFIG_CLI cannot reference Alibaba Cloud identity or regions" });
+        }
+    }
+    else if (value.aliyunAccountId == null || value.aliyunAssumeRoleId == null || !value.regions.length) {
+        context.addIssue({ code: "custom", message: "ALIYUN_ACK_ASSUME_ROLE requires accountId, assumeRoleId, and at least one region" });
+    }
+});
+export const ClusterSourceUpdateSchema = z.object({
+    displayName: z.string().trim().min(1).max(200),
+    aliyunAccountId: PositiveId.nullable(),
+    aliyunAssumeRoleId: PositiveId.nullable(),
+    regions: z.array(z.string().regex(/^[a-z0-9-]{1,80}$/u)).max(100),
+    enabled: z.boolean(),
+    expectedVersion: z.number().int().nonnegative()
+}).strict();
+export const ClusterObservationInputSchema = z.object({
+    observationKey: z.string().regex(/^obs_[0-9a-f]{64}$/u),
+    observedAt: z.string().datetime({ offset: true }).optional(),
+    observedName: z.string().trim().min(1).max(200).optional(),
+    provider: z.string().regex(/^[A-Za-z0-9._-]{1,40}$/u),
+    region: z.string().trim().min(1).max(80).optional(),
+    kubernetesVersion: z.string().trim().min(1).max(80).optional(),
+    providerClusterId: z.string().trim().min(1).max(320).optional(),
+    providerClusterIdSha256: Sha256.optional(),
+    kubeSystemUidSha256: Sha256.optional(),
+    endpointSha256: Sha256.optional(),
+    certificateAuthoritySha256: Sha256.optional()
+}).strict().superRefine((value, context) => {
+    if (value.providerClusterId != null && value.providerClusterIdSha256 == null) {
+        context.addIssue({ code: "custom", path: ["providerClusterIdSha256"], message: "providerClusterIdSha256 is required with providerClusterId" });
+    }
+});
+export const ClusterObservationBatchRequestSchema = z.object({
+    observations: z.array(ClusterObservationInputSchema).min(1).max(100)
+}).strict();
+export const ClusterAdoptRequestSchema = z.object({
+    code: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u),
+    name: z.string().trim().min(1).max(120),
+    description: z.string().trim().max(2000).optional(),
+    expectedVersion: z.number().int().nonnegative(),
+    reason: z.string().trim().min(5).max(1000)
+}).strict();
+export const ClusterLinkRequestSchema = z.object({
+    clusterKey: z.string().regex(/^clu_[0-9a-f]{32}$/u),
+    expectedCandidateVersion: z.number().int().nonnegative(),
+    expectedClusterVersion: z.number().int().nonnegative(),
+    reason: z.string().trim().min(5).max(1000)
+}).strict();
+export const ClusterIgnoreRequestSchema = z.object({
+    expectedVersion: z.number().int().nonnegative(),
+    reason: z.string().trim().min(5).max(1000)
+}).strict();
+export const ClusterObservationReceiptSchema = z.object({
+    observation: ClusterObservationViewSchema,
+    candidate: ClusterCandidateViewSchema,
+    replayed: z.boolean()
+});
+export const ClusterObservationBatchReceiptSchema = z.object({
+    items: z.array(ClusterObservationReceiptSchema),
+    observationCount: z.number().int().nonnegative(),
+    candidateCount: z.number().int().nonnegative(),
+    replayed: z.boolean()
+});
+export const ClusterCandidateDecisionViewSchema = z.object({
+    action: ClusterGovernanceActionSchema,
+    candidate: ClusterCandidateViewSchema,
+    cluster: ClusterSummarySchema.nullable().optional(),
+    replayed: z.boolean(),
+    decidedAt: NonEmptyString
+});
+export const ClusterDiscoveryRunViewSchema = z.object({
+    runNo: NonEmptyString,
+    sourceKey: NonEmptyString,
+    state: NonEmptyString,
+    discoveredCount: z.number().int().nonnegative(),
+    candidateCount: z.number().int().nonnegative(),
+    errorCode: OptionalString,
+    errorMessage: OptionalString,
+    startedAt: OptionalString,
+    completedAt: OptionalString
+});
+function pageSchema(item) {
+    return z.object({
+        items: z.array(item),
+        total: z.number().int().nonnegative(),
+        page: z.number().int().positive(),
+        size: z.number().int().positive(),
+        totalPages: z.number().int().nonnegative()
+    });
+}
+export const ClusterSummaryListSchema = z.array(ClusterSummarySchema);
+export const ClusterSourceListSchema = z.array(ClusterSourceViewSchema);
+export const ClusterCandidatePageSchema = pageSchema(ClusterCandidateViewSchema);
+export const ClusterObservationPageSchema = pageSchema(ClusterObservationViewSchema);
+export const ClusterApiErrorSchema = z.object({
+    code: z.string().optional(),
+    message: z.string().optional(),
+    requestId: z.string().optional(),
+    details: z.unknown().optional()
+});
+//# sourceMappingURL=schemas.js.map

package/dist/clusters/schemas.js.map

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

package/dist/command-catalog.js

@@ -375,6 +375,126 @@ export const COMMAND_CATALOG = [
         access: "authenticated",
         examples: ["numa media capabilities --json"]
     },
+    {
+        command: "repository connection list",
+        summary: "列出当前用户可用的安全 SCM connection inventory",
+        access: "authenticated",
+        operationalNotes: ["仅返回 code、name、provider、status 和 capabilities；不读取 admin 配置或凭据。"],
+        examples: ["numa repository connection list --json"]
+    },
+    {
+        command: "repository list [--status <state>] [--connection <code>] [--namespace <external-id>] [--owner-team-id <id>] [--management-mode <mode>] [--page <number>] [--size <number>]",
+        summary: "列出独立 Source Repository catalog",
+        access: "authenticated",
+        operationalNotes: ["使用平台 repositoryKey；不接受或输出 provider credential。"],
+        examples: ["numa repository list --connection codeup-main --json"]
+    },
+    {
+        command: "repository get <repository-key>",
+        summary: "查看一个独立 Source Repository catalog 项",
+        access: "authenticated",
+        examples: ["numa repository get repo_01 --json"]
+    },
+    {
+        command: "repository namespace list --connection <code> [--search <text>]",
+        summary: "发现指定 SCM connection 可用的 provider namespace",
+        access: "authenticated",
+        operationalNotes: ["只接受 connection code；不接受 provider URL、token、credential 或本地路径。"],
+        examples: ["numa repository namespace list --connection codeup-main --json"]
+    },
+    {
+        command: "repository remote list --connection <code> [--search <text>]",
+        summary: "分页发现 provider 中的远端仓库",
+        access: "authenticated",
+        examples: ["numa repository remote list --connection codeup-main --search order --json"]
+    },
+    {
+        command: "repository remote get <external-id> --connection <code>",
+        summary: "按 provider externalId 查看一个远端仓库",
+        access: "authenticated",
+        examples: ["numa repository remote get 123456 --connection codeup-main --json"]
+    },
+    {
+        command: "repository capabilities --connection <code> [--consumer <type>]",
+        summary: "查看 Source Repository 操作能力和服务端约束",
+        access: "authenticated",
+        examples: ["numa repository capabilities --connection codeup-main --consumer gitops --json"]
+    },
+    {
+        command: "repository status [run-no] [--client-request-id <id>]",
+        summary: "查询或恢复 Source Repository run；无目标时列出 runs",
+        access: "authenticated",
+        operationalNotes: ["结果未知时按原 clientRequestId 恢复；不能换一个幂等键重新提交。"],
+        examples: ["numa repository status --client-request-id create-order-20260822 --json"]
+    },
+    {
+        command: "repository events <run-no> [--after-sequence <number>]",
+        summary: "按单调 sequence 读取 Source Repository run 事件",
+        access: "authenticated",
+        examples: ["numa repository events run_01 --after-sequence 42 --json"]
+    },
+    {
+        command: "repository plan get <plan-no>",
+        summary: "读取并审阅不可变的服务端仓库计划",
+        access: "authenticated",
+        operationalNotes: ["返回服务端 planHash、blockers、warnings 和 sideEffects；不产生副作用。"],
+        examples: ["numa repository plan get RP-1 --json"]
+    },
+    {
+        command: "repository plan create --connection <code> --namespace <external-id> --name <name> [--initialization <empty|readme>]",
+        summary: "生成创建仓库的不可变服务端计划",
+        access: "role",
+        roles: ["mci-devops-platform-repository-planner", "mci-devops-platform-repository-operator"],
+        operationalNotes: ["先审阅 blockers、sideEffects 与 planHash；本命令不写 Provider。"],
+        examples: ["numa repository plan create --connection codeup-main --namespace 123 --name order-api --json"]
+    },
+    {
+        command: "repository plan register --connection <code> --external-id <id>",
+        summary: "生成接入既有远端仓库的不可变计划",
+        access: "role",
+        roles: ["mci-devops-platform-repository-planner", "mci-devops-platform-repository-operator"],
+        examples: ["numa repository plan register --connection codeup-main --external-id 456 --json"]
+    },
+    {
+        command: "repository plan use-existing --repository-key <key>",
+        summary: "生成复用受管仓库的不可变计划",
+        access: "role",
+        roles: ["mci-devops-platform-repository-planner", "mci-devops-platform-repository-operator"],
+        examples: ["numa repository plan use-existing --repository-key repo_01 --json"]
+    },
+    {
+        command: "repository plan disable --repository-key <key>",
+        summary: "生成停用受管仓库的不可变计划",
+        access: "role",
+        roles: ["mci-devops-platform-repository-planner", "mci-devops-platform-repository-operator"],
+        examples: ["numa repository plan disable --repository-key repo_01 --json"]
+    },
+    ...["create", "register", "disable"].map((action) => ({
+        command: `repository ${action} --plan-no <number> --plan-hash <hash> --client-request-id <id> --idempotency-key <key> --yes`,
+        summary: `按已审阅 plan 执行仓库${action === "create" ? "创建" : action === "register" ? "接入" : "停用"}`,
+        access: "role",
+        roles: ["mci-devops-platform-repository-operator"],
+        operationalNotes: ["client-request-id 与 idempotency-key 必须相同；结果未知时复用原值查询或重试。"],
+        examples: [`numa repository ${action} --plan-no RP-1 --plan-hash <64-hex> --client-request-id request-01 --idempotency-key request-01 --yes --json`]
+    })),
+    {
+        command: "repository retry <run-no> --yes",
+        summary: "重试服务端判定可恢复的仓库运行",
+        access: "role",
+        roles: ["mci-devops-platform-repository-operator"],
+        examples: ["numa repository retry RR-1 --yes --json"]
+    },
+    {
+        command: "repository reconcile <identifier> [--repository --idempotency-key <key>] --yes",
+        summary: "恢复仓库运行或重新观察受管仓库",
+        access: "role",
+        roles: ["mci-devops-platform-repository-operator"],
+        operationalNotes: [
+            "--repository 时必须提供并复用 idempotency-key。",
+            "legacy catalog 若缺 connectionCode、externalId 或 fullName，CLI 会标记 MIGRATION_REQUIRED 并拒绝不安全 reconcile。"
+        ],
+        examples: ["numa repository reconcile repo_01 --repository --idempotency-key observe-repo-01 --yes --json"]
+    },
     {
         command: "app scm list [--provider <github|codeup>] [--search <text>]",
         summary: "列出安全的 SCM 连接、缓存健康状态和能力",
@@ -388,6 +508,31 @@ export const COMMAND_CATALOG = [
         operationalNotes: ["仓库结果固定返回 externalId、defaultBranch 和 headRevision；选择后 headRevision 成为 expectedHead。"],
         examples: ["numa app scm inspect codeup-main --repositories --search order --limit 50 --json"]
     },
+    {
+        command: "app scm namespace list <code> [--search <text>] [--cursor <cursor>] [--limit <number>]",
+        summary: "分页查询 SCM provider 中可创建仓库的 namespace",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        operationalNotes: [
+            "Codeup 仓库创建必须使用返回的数字 externalId，而不是 namespace 显示路径。",
+            "JWT 由网关强制，最终 ops-admin Client Role 由 DevOps Controller 校验。"
+        ],
+        examples: ["numa app scm namespace list codeup-main --search platform --json"]
+    },
+    {
+        command: "app scm repository list <code> [--search <text>] [--cursor <cursor>] [--limit <number>]",
+        summary: "通过独立 SCM 生命周期 API 分页查询仓库",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        examples: ["numa app scm repository list codeup-main --search code-index --json"]
+    },
+    {
+        command: "app scm repository inspect <code> <external-id>",
+        summary: "通过 provider externalId 查询一个仓库",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        examples: ["numa app scm repository inspect codeup-main 123456 --json"]
+    },
     {
         command: "app scm probe <code> [--live --revision <number>]",
         summary: "查看缓存健康诊断，或由服务端授权执行 live probe",
@@ -426,6 +571,8 @@ export const COMMAND_CATALOG = [
         operationalNotes: [
             "非 TTY 必须提供 --spec，否则稳定返回 onboarding_input_required。",
             "--plan 只保存草稿并执行预检；--apply 使用服务端 planHash 提交异步任务。",
+            "schemaVersion=2 只引用 Repository Control Plane 的 repositoryPlanRef 或 repositoryRef。",
+            "交互 TUI 新会话固定使用 schemaVersion=2；legacy v1 会话只能恢复查看，不能由 TUI preflight/apply。",
             "结果不明时复用同一 idempotency-key，并用 inspect/resume 恢复，不能由客户端标记完成。"
         ],
         examples: ["numa app onboard --spec onboarding.json --apply --idempotency-key app-order-20260819 --json"]
@@ -458,8 +605,12 @@ export const COMMAND_CATALOG = [
     },
     {
         command: "app tui [--session <session-no>]",
-        summary: "打开可跨客户端恢复的 Application Onboarding TUI",
+        summary: "打开 v2 Repository Control Plane 入驻向导，或只读恢复 legacy v1 会话",
         access: "authenticated",
+        operationalNotes: [
+            "新草稿固定为 schemaVersion=2；CREATE_NEW 输入 planNo/planHash，ATTACH_EXISTING 选择或输入 repositoryKey/expectedHead。",
+            "legacy schemaVersion=1 会话不会被注入或伪装成 v2，TUI preflight/apply 固定 fail-closed。"
+        ],
         examples: ["numa app tui --session 8d15ee89-43f0-4378-a7aa-51f09c5b42fc"]
     },
     ...["retry", "reassess", "cancel"].map((action) => ({
@@ -509,6 +660,149 @@ export const COMMAND_CATALOG = [
         ],
         examples: ["numa app candidate adopt 123 --yes --json"]
     },
+    {
+        command: "gitops repository list [--status <status>] [--search <text>] [--cursor <cursor>] [--limit <number>]",
+        summary: "列出平台登记的 GitOps 仓库及健康状态",
+        access: "authenticated",
+        operationalNotes: ["仅使用平台 stable key；不接受任意仓库 URL、分支或本地 clone 路径。"],
+        examples: ["numa gitops repository list --json"]
+    },
+    {
+        command: "gitops repository get <repository-key>",
+        summary: "查看 GitOps 仓库登记、写入策略和最近探测信息",
+        access: "authenticated",
+        examples: ["numa gitops repository get mci-flux --json"]
+    },
+    {
+        command: "gitops repository probe <repository-key>",
+        summary: "由平台使用已登记 SCM 连接探测 GitOps 仓库",
+        access: "authenticated",
+        operationalNotes: ["CLI 不发送仓库 URL 或 Git 凭据。"],
+        examples: ["numa gitops repository probe mci-flux --json"]
+    },
+    {
+        command: "gitops target list [--status <status>] [--environment-id <id>] [--cursor <cursor>] [--limit <number>]",
+        summary: "列出多集群 GitOps Deployment targets",
+        access: "authenticated",
+        operationalNotes: ["Phase 1 服务端仅支持 status 和 environmentId 过滤。"],
+        examples: ["numa gitops target list --environment-id 12 --status active --json"]
+    },
+    {
+        command: "gitops target get <target-key>",
+        summary: "查看环境、集群、namespace、Flux installation 和仓库绑定",
+        access: "authenticated",
+        examples: ["numa gitops target get mci-dev-primary --json"]
+    },
+    {
+        command: "gitops target validate <target-key>",
+        summary: "执行 Phase 1 target topology-only 拓扑关系检查",
+        access: "authenticated",
+        operationalNotes: ["当前不宣称已校验 SCM 内容、overlay 文件、Flux 运行状态或 Jenkins image writer。"],
+        examples: ["numa gitops target validate mci-dev-primary --json"]
+    },
+    {
+        command: "gitops profile list [--status <status>] [--search <text>] [--cursor <cursor>] [--limit <number>]",
+        summary: "列出可复用的 GitOps layout profile 版本",
+        access: "authenticated",
+        examples: ["numa gitops profile list --status active --json"]
+    },
+    {
+        command: "gitops profile get <profile-code>",
+        summary: "查看 layout profile 及服务端返回的版本列表",
+        access: "authenticated",
+        examples: ["numa gitops profile get MCI_FLUX_V1 --json"]
+    },
+    {
+        command: "gitops service import --application <code> --target <target-key> [--profile <code>] [--profile-version <version>] --idempotency-key <key>",
+        summary: "从受管 target 的锁定 SCM revision 导入 MCI_FLUX_V1 服务绑定",
+        access: "role",
+        roles: [
+            "mci-devops-platform-gitops-planner",
+            "mci-devops-platform-gitops-operator",
+            "mci-devops-platform-ops-admin"
+        ],
+        operationalNotes: [
+            "非 ops-admin 调用者还必须是应用 governing team 的 MEMBER；平台 ops-admin 可执行应急管理操作。",
+            "Idempotency-Key 对同一应用唯一；结果不明时必须复用原值，不能用新键重试。",
+            "导入只读取受管 SCM 并持久化 binding/snapshot，不写 SCM、不改变 image tag。"
+        ],
+        examples: ["numa gitops service import --application code-index --target mci-dev-primary --idempotency-key code-index-dev-import-1 --json"]
+    },
+    {
+        command: "gitops service plan --application <code> --target <target-key> [--profile <code>] [--profile-version <version>] [--service-id <id>] --spec <file>",
+        summary: "使用唯一受管 MCI_FLUX_V1 renderer 生成并持久化结构变更计划",
+        access: "role",
+        roles: [
+            "mci-devops-platform-gitops-planner",
+            "mci-devops-platform-gitops-operator",
+            "mci-devops-platform-ops-admin"
+        ],
+        operationalNotes: [
+            "非 ops-admin 调用者还必须是应用 governing team 的 MEMBER；service-id 是已有 binding 的字符串标识。",
+            "spec 禁止整个 image 及应用、环境、namespace、release、仓库、分支和 Flux 路径等平台受管字段。",
+            "计划锁定 target/profile version/base revision/canonicalSpecHash/planHash，只持久化 plan/snapshot，不写 SCM。",
+            "执行必须另行调用 apply；当前 CLI 仍不开放 observe。"
+        ],
+        examples: ["numa gitops service plan --application code-index --target mci-dev-primary --spec gitops-service.json --json"]
+    },
+    {
+        command: "gitops service apply <plan-number> --plan-hash <64-hex> --idempotency-key <key> --yes",
+        summary: "按不可变服务端计划执行受管 GitOps 结构变更",
+        access: "role",
+        roles: ["mci-devops-platform-gitops-operator", "mci-devops-platform-ops-admin"],
+        operationalNotes: [
+            "必须原样提交 planNumber 和 64 位 lower-case planHash；CLI 不接受仓库、路径、分支或镜像参数。",
+            "未知结果必须使用同一 plan 和 Idempotency-Key 重试，不能换键重新提交。",
+            "生产 target 由服务端强制 ops-admin；非生产要求 gitops-operator 和应用团队 MAINTAINER。",
+            "DIRECT_BRANCH 可直接完成；REVIEWED_CHANGE 可进入 WAITING_REVIEW 并返回 reviewUrl。"
+        ],
+        examples: ["numa gitops service apply gplan_01 --plan-hash <64-hex> --idempotency-key code-index-dev-apply-1 --yes --json"]
+    },
+    {
+        command: "gitops service status <run-number>",
+        summary: "按 stable runNo 或数字 ID 查询 GitOps change run",
+        access: "role",
+        roles: [
+            "mci-devops-platform-gitops-reader",
+            "mci-devops-platform-gitops-planner",
+            "mci-devops-platform-gitops-operator",
+            "mci-devops-platform-ops-admin"
+        ],
+        operationalNotes: ["非 ops-admin 调用者还必须是关联应用 governing team 的 VIEWER。"],
+        examples: ["numa gitops service status gplan_01 --json", "numa gitops service status 42 --json"]
+    },
+    {
+        command: "gitops service events <run-number>",
+        summary: "按 stable runNo 或数字 ID 读取 GitOps change run 事件",
+        access: "role",
+        roles: [
+            "mci-devops-platform-gitops-reader",
+            "mci-devops-platform-gitops-planner",
+            "mci-devops-platform-gitops-operator",
+            "mci-devops-platform-ops-admin"
+        ],
+        operationalNotes: [
+            "非 ops-admin 调用者还必须是关联应用 governing team 的 VIEWER。",
+            "事件按 sequence 升序返回，type/createdAt/details 是 eventType/occurredAt/output 的稳定别名。"
+        ],
+        examples: ["numa gitops service events gplan_01 --json", "numa gitops service events 42 --json"]
+    },
+    {
+        command: "gitops service evidence <service-binding-id>",
+        summary: "查看 Jenkins 镜像更新与独立 Flux runtime observation 证据",
+        access: "role",
+        roles: [
+            "mci-devops-platform-gitops-reader",
+            "mci-devops-platform-gitops-planner",
+            "mci-devops-platform-gitops-operator",
+            "mci-devops-platform-ops-admin"
+        ],
+        operationalNotes: [
+            "非 ops-admin 调用者还必须是关联 service binding governing team 的 VIEWER。",
+            "CLI 仅查询证据，不开放内部 observe 写接口；JENKINS_ATTESTED 不能单独把 target 标记为 ACTIVE。"
+        ],
+        examples: ["numa gitops service evidence 77 --json"]
+    },
     {
         command: "pipeline list [--app <code>] [--tier <tier>] [--branch <name>]",
         summary: "列出当前用户可见的 Jenkins 应用流水线",
@@ -632,6 +926,81 @@ export const COMMAND_CATALOG = [
         access: "authenticated",
         examples: ["numa media library publish --manifest library-entry.json --json"]
     },
+    {
+        command: "cluster list",
+        summary: "列出 Cluster Control Plane 中已治理的跨集群 inventory",
+        access: "role",
+        roles: ["mci-devops-platform-cluster-reader", "mci-devops-platform-ops-admin"],
+        examples: ["numa cluster list --json"]
+    },
+    {
+        command: "cluster read <cluster-key>",
+        summary: "按 stable clusterKey 查看脱敏集群详情和身份指纹类型",
+        access: "role",
+        roles: ["mci-devops-platform-cluster-reader", "mci-devops-platform-ops-admin"],
+        examples: ["numa cluster read clu_0123456789abcdef0123456789abcdef --json"]
+    },
+    {
+        command: "cluster run <run-no>",
+        summary: "查询 ACK discovery 异步运行状态",
+        access: "role",
+        roles: ["mci-devops-platform-cluster-reader", "mci-devops-platform-ops-admin"],
+        examples: ["numa cluster run cdr_01 --json"]
+    },
+    ...["sources [source-key]", "candidates [candidate-key]", "observations [observation-key]"].map((command) => ({
+        command: `cluster ${command}`,
+        summary: `读取脱敏 cluster ${command.split(" ")[0]} inventory`,
+        access: "role",
+        roles: ["mci-devops-platform-cluster-reader", "mci-devops-platform-ops-admin"],
+        examples: [`numa cluster ${command.split(" ")[0]} --json`]
+    })),
+    {
+        command: "cluster source create --source-key <key> --type <kubeconfig|ack> --display-name <name> [--aliyun-account-id <id> --aliyun-assume-role-id <id> --region <region>...] --idempotency-key <key> --yes",
+        summary: "登记 kubeconfig CLI 或 ACK assume-role discovery source",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        operationalNotes: ["ACK 只引用平台 accountId 和必选 ACTIVE assumeRoleId；CLI/浏览器不接触 AK/SK。"],
+        examples: ["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"]
+    },
+    {
+        command: "cluster source update <source-key> --expected-version <number> --idempotency-key <key> --yes",
+        summary: "用乐观锁和幂等键更新 discovery source",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        examples: ["numa cluster source update ack-prod --expected-version 2 --enable --idempotency-key source-ack-prod-v2 --yes --json"]
+    },
+    {
+        command: "cluster source discover <source-key> --idempotency-key <key> --yes",
+        summary: "启动 ACK assume-role source 的服务端只读发现",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        examples: ["numa cluster source discover ack-prod --idempotency-key discover-ack-prod-20260822 --yes --json"]
+    },
+    ...["adopt", "link", "ignore"].map((action) => ({
+        command: `cluster candidate ${action} <candidate-key> --idempotency-key <key> --yes`,
+        summary: `${action} cluster discovery candidate，并持久化审计原因和乐观锁版本`,
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        examples: [`numa cluster candidate ${action} cand_01 --help`]
+    })),
+    {
+        command: "cluster discover kubeconfig [--context <name>] [--kubeconfig <file>] [--timeout <seconds>]",
+        summary: "本地只读调用 kubectl 并输出可审阅的严格脱敏 JSON plan",
+        access: "public",
+        operationalNotes: [
+            "使用 execFile 参数数组和短超时；不会输出或上传 endpoint、kube-system UID、CA、user、token、cert、exec、auth-provider 或 kubectl stderr。",
+            "只输出 raw ACK providerClusterId；endpoint、UID、CA 仅输出服务端可校验 SHA-256。"
+        ],
+        examples: ["numa cluster discover kubeconfig --json > cluster-discovery.json"]
+    },
+    {
+        command: "cluster discover submit --file <plan.json> --source <source-key> --idempotency-key <key> --yes",
+        summary: "把已审阅的本地 kubeconfig discovery plan 原子批量提交",
+        access: "role",
+        roles: ["mci-devops-platform-ops-admin"],
+        operationalNotes: ["discover 与 submit 分离；未知结果必须用同一 source、plan 和 Idempotency-Key 重放，禁止逐 context 循环提交。"],
+        examples: ["numa cluster discover submit --file cluster-discovery.json --source local-kubeconfig --idempotency-key kube-observe-20260822-01 --yes --json"]
+    },
     {
         command: "serve",
         summary: "运行兼容的 stdio MCP 服务",