fix: 收敛 PaC 自动交付提示

2026-07-11 11:42:16 +02:00
parent b12dd85375
commit b607c3a996
55 changed files with 2953 additions and 1472 deletions
@@ -1,36 +1,74 @@
 // SPEC: PJ2026-01060703 CI/CD branch follower help text.
-// Responsibility: bounded CLI help payloads for the branch-follower entrypoint.
+// Responsibility: bounded, authority-scoped CLI help for the retired branch-follower entrypoint.
+import type { BranchFollowerScope } from "./cicd-types";

-export function buildCicdHelp(configPath: string, spec: string): unknown {
+export function buildCicdHelp(
+  configPath: string,
+  spec: string,
+  scope: BranchFollowerScope = "default",
+  legacyConfigured = false,
+): unknown {
+  if (scope === "retired-maintenance") {
+    return {
+      command: "cicd branch-follower retired-maintenance cleanup-state",
+      scope,
+      mutation: "explicit-confirm-required",
+      usage: [
+        "bun scripts/cli.ts cicd branch-follower retired-maintenance cleanup-state --all --dry-run",
+        "bun scripts/cli.ts cicd branch-follower retired-maintenance cleanup-state --all --confirm",
+      ],
+      boundary: "仅清理 owning YAML 已标记 retired-readonly 的历史 follower state；不得触发、恢复或补齐交付。",
+      config: configPath,
+      spec,
+    };
+  }
+  if (scope === "legacy-cicd") {
+    return {
+      command: "cicd branch-follower legacy-cicd",
+      scope,
+      configured: legacyConfigured,
+      mutation: legacyConfigured ? "explicit-confirm-required" : false,
+      usage: legacyConfigured
+        ? [
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd plan --follower <id>",
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd apply --confirm --wait",
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd run-once --follower <id> --confirm --wait",
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd debug-step --follower <id> --step state-write --confirm",
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd job --follower <id> --job <name>",
+            "bun scripts/cli.ts cicd branch-follower legacy-cicd gate --follower <id> --gate <name> --confirm",
+          ]
+        : [],
+      boundary: legacyConfigured
+        ? "仅 owning YAML 精确声明 legacy-manual 的 follower 可执行；PaC、retired-readonly 与 unknown 一律 fail-closed。"
+        : "当前 owning YAML 未配置 legacy-manual follower；本 scope 不提供写入口。",
+      config: configPath,
+      spec,
+    };
+  }
  return {
-    command: "cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs|taskrun|job|runtime|gate",
+    command: "cicd branch-follower status|events|logs|taskrun|runtime|debug-step",
    deprecated: true,
-    mode: "retired-readonly-for-jd01-consumers",
+    mode: "retired-readonly",
    replacement: "bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01",
-    issue: "https://github.com/pikasTech/unidesk/issues/1560",
-    output: "text by default; use --json, --raw, or -o json|yaml for machine output",
+    output: "默认输出文本；机器输出使用 --json、--raw 或 -o json|yaml",
    usage: [
      "bun scripts/cli.ts cicd branch-follower status",
-      "bun scripts/cli.ts cicd branch-follower status --live",
-      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step controller-source",
-      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step state-read",
      "bun scripts/cli.ts cicd branch-follower events --follower agentrun-jd01-v02",
      "bun scripts/cli.ts cicd branch-follower logs --follower web-probe-sentinel-master",
      "bun scripts/cli.ts cicd branch-follower taskrun --follower hwlab-jd01-v03 --taskrun runtime-ready --logs-tail 120 --json",
-      "bun scripts/cli.ts cicd branch-follower job --follower agentrun-jd01-v02 --source-commit <sha> --job image-build --json",
-      "bun scripts/cli.ts cicd branch-follower gate --follower hwlab-jd01-v03 --gate control-plane-refresh --source-commit <sha> --confirm --json",
-      "bun scripts/cli.ts cicd branch-follower gate --follower hwlab-jd01-v03 --gate git-mirror-flush --source-commit <sha> --confirm --json",
-      "bun scripts/cli.ts cicd branch-follower gate --follower hwlab-jd01-v03 --gate runtime-closeout --source-commit <sha> --confirm --json",
-      "bun scripts/cli.ts cicd branch-follower gate --follower agentrun-jd01-v02 --gate reuse-plan --source-commit <sha> --json",
+      "bun scripts/cli.ts cicd branch-follower runtime --follower hwlab-jd01-v03 --json",
+      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step controller-source",
+      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step state-read",
+      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step status-read",
+      "bun scripts/cli.ts cicd branch-follower debug-step --follower web-probe-sentinel-master --step decide",
    ],
    config: configPath,
    spec,
-    description: "Retired branch-follower controller surface for the JD01 migrated consumers. Use PaC status/history for current closeout; branch-follower commands remain only for historical state and bounded migration diagnostics.",
-    currentCloseout: [
-      "bun scripts/cli.ts platform-infra gitea mirror status --target JD01",
-      "bun scripts/cli.ts platform-infra gitea mirror webhook status --target JD01",
-      "bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01",
-      "bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --limit 10",
-    ],
+    description: "退役 branch-follower 的只读历史状态与有界下钻入口；当前交付只观察 PaC 自动链。",
+    next: {
+      status: "bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01",
+      history: "bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --limit 10",
+      fixAutomaticDelivery: "docs/reference/platform-infra.md#gitea-与-pipelines-as-code-边界",
+    },
  };
 }