fallow-cloud-setup

Fallow Cloud 设置：使用一个 commit SHA 进行运行时覆盖率分析

只有在以下五项都指向同一个 commit SHA 时，Fallow Cloud 才会将生产环境运行时覆盖率与代码关联起来：

1. 应用中的 beacon 发送 commitSha。
2. CI 上传该 SHA 对应的静态清单。
3. 如果构建会打包代码，CI 上传该 SHA 对应的 source maps。
4. CI 注册该 SHA 对应的部署。
5. 收到该 SHA 对应的第一批生产环境数据。

fallow coverage setup --cloud --json 会为以上五个步骤生成计划。本技能将执行该计划。

适用场景

• 将 Fallow beacon 添加到应用，并将生产环境覆盖率数据发送到 Fallow Cloud。
• 配置 CI 步骤，以便上传清单和 source maps，并注册部署。
• 当 Fallow Cloud 未显示数据或仓库没有匹配的函数时，查找缺失的步骤。

不适用场景

• 本地代码质量工具、CI 质量门禁或 Agent 配置。请使用 fallow-setup。
• 读取已完成设置的仓库的运行时数据。请使用 fallow。

规则

1. 绝不将 API 密钥值写入文件、命令或消息。使用计划提供的环境变量名称（cloud.api_key_env、cloud.browser_key_env）。用户会将密钥值存储为 CI 密钥和服务器环境变量。绝不使用 --api-key 标志，也绝不将密钥放在命令前（FALLOW_API_KEY=... npx ...）。用户会在 shell 中导出密钥。
2. 浏览器 bundle 只能使用仅限数据写入的密钥（前缀为 fallow_pub_k1_）。完整密钥（前缀为 fallow_live_k1_）必须保留在 CI 和服务器上。
3. 所有步骤都使用同一个 commit SHA。不要将计划中的 $GITHUB_SHA 或 commitSha 表达式替换为其他值。
4. 根据 fallow coverage setup --help 确定标志。不要凭记忆使用标志。
5. 更改 CI 工作流前，先向用户展示编辑内容。部署工作流可能包含密钥并拥有生产环境访问权限。

流程

1. 检查标志。 运行 npx fallow coverage setup --help。如果输出中没有列出 --cloud，请改用手动设置，而不是执行步骤 2 到 8。手动设置包含相同的五个步骤。

2. 获取计划。 在仓库根目录运行 npx fallow coverage setup --cloud --json。如果 cloud.project_id 为 null，请向用户询问 Fallow Cloud 项目 ID（owner/repo），然后使用 --project-id <owner/repo> 再次运行命令，以免任何代码片段保留 OWNER/REPO 占位符。如果命令以 2 退出且没有输出 JSON，请读取 stderr 中的错误信息：项目 ID、--git-sha 或 --api-endpoint 等输入无效。

3. 阅读计划。

   • members[] 中每个条目对应一个会运行代码的工作区成员。每个条目都有自己的 snippets、files_to_edit、dockerfile_snippet 和 warnings。只应用 members[] 中的代码片段：顶层的 snippets 和 files_to_edit 是第一个成员的重复内容。
   • commands 用于安装 beacon。
   • cloud.ci.steps 包含 GitHub Actions 步骤（cloud.ci.provider 为 github_actions）。cloud.ci.workflows_detected 列出看起来用于部署的工作流文件。
   • cloud.source_maps.dirs 列出每个打包成员的构建输出目录。cloud.source_maps.reason 说明构建必须执行的操作，例如生成源映射。
   • warnings 列出计划无法代为处理的事项，例如 Node 服务的覆盖率来源。

4. 安装 beacon。 使用项目的包管理器运行 commands 中的命令。

5. 添加代码片段。 对于每个成员，将每个代码片段添加到其 path 指定的文件中。保留代码片段中的 projectId、commitSha、coverageOrigin 和 runtimeSurface 值。如果文件已存在，将代码片段添加到入口模块的开头。不要替换文件。

6. 将提交 SHA 传递给运行时。

   • 浏览器包：在构建步骤中设置 VITE_FALLOW_COMMIT_SHA（CI 步骤中会显示）。
   • 容器中的服务：将 dockerfile_snippet 中的行添加到 Dockerfile，并使用 --build-arg FALLOW_COMMIT_SHA=$GITHUB_SHA 进行构建。
   • 平台上的服务：代码片段会读取 Vercel、Render 或 Railway 设置的 SHA。在其他平台上，请在运行时环境中设置 FALLOW_COMMIT_SHA。

7. 添加 CI 步骤。 将 cloud.ci.steps 添加到执行构建和部署的作业中，位置在 cloud.ci.workflows_detected 指定的工作流文件内。如果该列表为空，或项目未使用 GitHub Actions，请询问用户哪个作业负责部署，并相应调整这些步骤。检出时需要设置 fetch-depth: 0。上传步骤放在构建步骤之后，且构建必须生成源映射，上传才能发送内容。注册步骤放在部署步骤之后。遵循 cloud.ci.instructions。

8. 告知用户手动操作事项。 用户需在 Fallow Cloud 控制面板中创建密钥，将其保存为计划指定的机密，然后进行部署。

9. 部署后检查设置。 请用户在 shell 中导出 FALLOW_API_KEY（完整密钥）。使用计划中的 cloud.wait_command，添加 --json，并将 $DEPLOYED_SHA 设置为已部署的提交 SHA 后运行。该命令会携带项目 ID。然后读取退出码：

   • 0：所有步骤均已完成。
   • 1：超时。读取 cloud.wait.activation.next。其中会指出当前要执行的步骤，并在有相应命令时给出命令。当读取未成功时，activation 为 null；next.command 也可能为 null。
   • 2：发生错误。读取 cloud.wait.message；如果 stdout 中没有 JSON，则读取 stderr。

   激活信息正文可能包含此技能未提及的步骤 ID 和状态。请按原样报告。

常见问题

• beacon 为 problem：信标没有发送提交 SHA。请检查步骤 5。
• runtime 一直为 waiting：应用尚无生产流量，或者信标的 commitSha 不是 CI 使用的完整 SHA。
• deployment 为 waiting：仍有较早的部署接收运行时数据。新部署收到首条运行时数据后，就会成为当前部署。
• overlap 为 waiting：目前运行的函数太少。请发送更多流量。
• 对于不使用捆绑包、直接运行源文件的应用，source_maps 为 missing：当运行时数据加入清单后，它会变为 not_needed。
• overlap 为 problem：运行时路径与清单路径不匹配。例如，如果容器在其他根目录下运行代码（如 /app），则需要在 upload-inventory 上使用 --path-prefix。捆绑应用需要源映射。
• CI 中的 inventory 失败：检出为浅克隆。请设置 fetch-depth: 0。

参考

• 手动设置：手动完成五个步骤，适用于没有 --cloud 的废弃版本。