cloudflare/kumo
Publicmirrored fromhttps://github.com/cloudflare/kumoAvailable
ci/AGENTS.md
107lines · modecode
| 1 | # CI/CD Scripts |
| 2 | |
| 3 | TypeScript scripts + shell scripts for validation, reporting, versioning, and deployment. 6 GitHub Actions workflows in `.github/workflows/`. |
| 4 | |
| 5 | **Parent:** See [root AGENTS.md](../AGENTS.md) for monorepo context. |
| 6 | |
| 7 | ## STRUCTURE |
| 8 | |
| 9 | ``` |
| 10 | ci/ |
| 11 | ├── tsconfig.json # ES2022, strict, Node types |
| 12 | ├── reporters/ |
| 13 | │ ├── types.ts # Core types + artifact I/O (ci/reports/*.json) |
| 14 | │ ├── index.ts # Reporter registry + re-exports |
| 15 | │ ├── npm-release.ts # NPM beta install instructions (priority 10) |
| 16 | │ ├── kumo-docs-preview.ts # Docs preview URL (priority 30) |
| 17 | │ └── visual-regression.ts # Screenshot diff report |
| 18 | ├── scripts/ |
| 19 | │ ├── validate-kumo-changeset.ts # Pre-push + CI changeset enforcement |
| 20 | │ ├── ensure-changeset-config.ts # Guard: .changeset/config.json exists |
| 21 | │ ├── write-npm-report.ts # Writes ci/reports/npm-release.json |
| 22 | │ ├── write-kumo-docs-report.ts # Writes ci/reports/kumo-docs-preview.json |
| 23 | │ ├── post-pr-report.ts # Aggregates artifacts → GitHub PR comment |
| 24 | │ └── create-release-pr.ts # Creates release PR via GitHub API |
| 25 | ├── utils/ |
| 26 | │ ├── git-operations.ts # Git ref detection (CI + local), diff, changed files |
| 27 | │ ├── github-api.ts # Octokit wrapper (hardcoded: cloudflare/kumo) |
| 28 | │ └── pr-reporter.ts # Markdown assembly + comment posting |
| 29 | ├── visual-regression/ |
| 30 | │ └── run-visual-regression.ts # Creates vr-screenshots-{pr}-{runId} branches |
| 31 | └── versioning/ |
| 32 | ├── version-beta.sh # changeset version + append -beta.<sha> via jq |
| 33 | ├── publish-beta.sh # Full pipeline: version → build → publish → verify (45s) → report |
| 34 | ├── release-production.sh # Branch → version → build → publish → verify (30s) → push → PR |
| 35 | ├── deploy-kumo-docs-preview.sh # Build → wrangler versions upload → preview URL → report |
| 36 | └── deploy-kumo-docs-staging.sh # Build → wrangler deploy --env staging |
| 37 | ``` |
| 38 | |
| 39 | ## WHERE TO LOOK |
| 40 | |
| 41 | | Task | Location | Notes | |
| 42 | | -------------------- | -------------------------------------------- | ------------------------------------------------------- | |
| 43 | | Changeset validation | `scripts/validate-kumo-changeset.ts` | Used by lefthook pre-push AND CI | |
| 44 | | PR comment system | `reporters/` + `scripts/post-pr-report.ts` | Artifact bus via `ci/reports/*.json` | |
| 45 | | Beta release | `versioning/publish-beta.sh` | Calls version-beta.sh internally | |
| 46 | | Production release | `versioning/release-production.sh` | Creates release branch + PR | |
| 47 | | Git operations | `utils/git-operations.ts` | Dual-mode: GitHub Actions env vars / local `merge-base` | |
| 48 | | Visual regression | `visual-regression/run-visual-regression.ts` | Creates ephemeral branches for screenshot diffs | |
| 49 | |
| 50 | ## CONVENTIONS |
| 51 | |
| 52 | ### Artifact Bus Pattern |
| 53 | |
| 54 | Jobs communicate via filesystem: each writes JSON to `ci/reports/{id}.json`, final job reads all. |
| 55 | |
| 56 | ``` |
| 57 | publish-beta.sh → write-npm-report.ts → ci/reports/npm-release.json ──┐ |
| 58 | ├→ post-pr-report.ts → PR comment |
| 59 | deploy-docs-preview.sh → write-kumo-docs-report.ts → ci/reports/kumo-docs-preview.json ─┘ |
| 60 | ``` |
| 61 | |
| 62 | - Priority determines display order (lower = higher in comment): npm=10, docs=30 |
| 63 | - Reporter returns `null` to skip (e.g., no package version = no npm section) |
| 64 | - `readReportArtifacts()` handles partial failures via `failures` array |
| 65 | |
| 66 | ### Shell ↔ TypeScript Boundary |
| 67 | |
| 68 | - Shell scripts: orchestration (npm auth, git config, sequential builds, wrangler) |
| 69 | - TypeScript: structured operations (report generation, PR creation, GitHub API) |
| 70 | - Data channel: environment variables (`PACKAGE_VERSION`, `KUMO_DOCS_PREVIEW_URL`, `GITHUB_*`) |
| 71 | |
| 72 | ### Dual-Mode Git Operations |
| 73 | |
| 74 | `getGitRefs()` adapts automatically: |
| 75 | |
| 76 | - **CI**: Uses `GITHUB_BASE_REF` / `GITHUB_HEAD_REF` |
| 77 | - **Local**: Computes `git merge-base origin/main HEAD` |
| 78 | - Uses `execFileSync` (array args) to prevent shell injection |
| 79 | |
| 80 | ## GITHUB WORKFLOWS |
| 81 | |
| 82 | | Workflow | Trigger | Purpose | |
| 83 | | -------------------- | -------------------------------- | ------------------------------------------------ | |
| 84 | | `release.yml` | push:main | changesets/action (Version PR or publish) | |
| 85 | | `pullrequest.yml` | pull_request, push:opencode/\*\* | Build, lint, typecheck, test | |
| 86 | | `preview.yml` | pull_request, push:opencode/\*\* | pkg-pr-new, docs build/deploy, visual regression | |
| 87 | | `preview-deploy.yml` | workflow_run(Preview) | Fork PR docs deploy (security boundary) | |
| 88 | | `bonk.yml` | issue_comment, pr_review_comment | AI agent (`@ask-bonk`) via CF AI Gateway | |
| 89 | | `reviewer.yml` | pr_review_comment | AI code review (`/review` command) | |
| 90 | |
| 91 | ## ANTI-PATTERNS |
| 92 | |
| 93 | | Pattern | Why | Instead | |
| 94 | | ---------------------------------------- | ---------------------- | -------------------------------------- | |
| 95 | | Reading `process.env.*` directly | Bypasses typed context | Use `buildContextFromEnv()` | |
| 96 | | Adding reporter without registry | Won't be collected | Add to `reporters/index.ts` array | |
| 97 | | Running `release-production.sh` as agent | Sensitive operation | Human-only; use `DRY_RUN=true` to test | |
| 98 | |
| 99 | ## NOTES |
| 100 | |
| 101 | - **Verify-after-publish**: Both beta (45s) and production (30s) scripts sleep then check npm registry. No retry logic. |
| 102 | - **`DRY_RUN=true`**: Production release script gates all destructive operations; logs what would happen |
| 103 | - **Hardcoded repo**: `github-api.ts` uses `owner: "cloudflare", repo: "kumo"` |
| 104 | - **Required secrets**: `NPM_TOKEN`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `GITHUB_TOKEN`, `FIGMA_TOKEN` (optional) |
| 105 | - **Visual regression**: Creates ephemeral `vr-screenshots-{pr}-{runId}` branches for diff images |
| 106 | - **Fork PR security**: `preview-deploy.yml` handles fork PRs via `workflow_run` (no secrets in fork context) |
| 107 | - **Composite action**: `.github/actions/install-dependencies/action.yml` installs pnpm 10.22.0, Node 24, with optional filter |
| 108 | |