// SPEC: PJ2026-01060703 CI/CD branch follower help text.
// 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,
  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 status|events|logs|taskrun|runtime|debug-step",
    deprecated: true,
    mode: "retired-readonly",
    replacement: "bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01",
    output: "默认输出文本；机器输出使用 --json、--raw 或 -o json|yaml",
    usage: [
      "bun scripts/cli.ts cicd branch-follower status",
      "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 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: "退役 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-边界",
    },
  };
}