@devries-cameron20 / composio-1 / commits / bfdb8a661
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(release): harden the SDK release workflow after its first run (#5281)

<!-- sdk-release-note-exempt: python/pyproject.toml only adds the dev-only docs-reference dependency group used by the reference generator; the published Python SDK and its dependencies are unchanged. --> This PR: - part of [PLEN-4846](https://linear.app/composio/issue/PLEN-4846/map-sdk-release-betas-explicit-state-machines-and-verification) - makes `merged` a required field (a missing one is a contract failure, not an abandoned release) and judges each required check by its newest run - makes GitHub failures report GitHub's message, request ID and API version; retries rate limits for every method, 5xx and timeouts for GET only; adds `timeout-minutes` to every release job - adds a `regate` dispatch on `next` that re-runs the unchanged gate for a merged release a gate bug left untagged, and leaves an already-tagged release alone - checks npm trusted-publishing login per package before any upload (no more bare `ENEEDAUTH`), names "Allow npm dist-tag" on a dist-tag 403, and waits up to 20 minutes for npm's publish-time scan, so a re-run during the scan does not upload again - adds an `SDK candidate docs` check on stable release PRs that installs the docs against the candidate packages through a job-local registry; it replaces `typescript-check` in the stable gate, which the PR docs workflows now skip on `sdk-release/batch-*` heads - adds a `Docs - SDK reference drift` check on PRs to `next`, with `griffe` pinned in the `docs-reference` uv group, and updates the runbook (recovery table, GitHub incidents, npm trusted publishing) ## Context The first run of `sdk.release.yml` (2026-11-06 to 2026-11-09) needed a revert (https://github.com/ComposioHQ/composio/pull/5275), a re-request (https://github.com/ComposioHQ/composio/pull/5278), manual npm fixes and a manual dist-tag move, and still shipped a guide (`custom-mcp.mdx`, `appUrl`) that breaks against 0.29.0. The workflow had been built against assumed GitHub and npm behavior. The post-publish docs pin PR stays: pinning docs inside the release PR was dropped, because `next` would pin versions npm does not serve until publishing finishes. So the post-publish `docs` job keeps the `RELEASE_BOT_*` credentials (same App and client ID): `SDK_RELEASE_APP_PRIVATE_KEY` lives in `sdk-release-control`, which only admits `next`, and that job runs on the release tag. Testing: `pnpm run test:sdk-release` (187 pass), `typecheck:sdk-release`, oxlint, actionlint and zizmor on the release workflows, `test:release-workflow`. I simulated the drift check locally (clean tree green, an edited Python signature red). I reproduced twoslash error 2353 with `appUrl` against `@composio/core@0.29.0`. I also ran the production read path against live GitHub for release https://github.com/ComposioHQ/composio/pull/5278 with writes blocked (25 reads, 0 writes): regate found the release, the gate passed every check that existed then, regate reported it already tagged, and both real candidate artifacts were adopted. The next real stable release is the end-to-end proof. ## Unapplied review findings - [ ] P3 — `scripts/sdk-release/registry.ts` — a request timeout or transport error inside the 20-minute registry wait still fails the wait at once (a re-run is safe) - [ ] P3 — `scripts/sdk-release/npm-oidc.ts` — an npm exchange 429/5xx is not retried (it fails before any upload) - [ ] P3 — `.github/workflows/docs-tests.yml:25`, `docs-typescript-check.yml:23` — the `sdk-release/batch-*` skip applies to any branch with that prefix - [ ] P3 — `scripts/sdk-release/candidate-registry.ts` — the candidate docs install re-resolves the docs lock instead of installing it frozen - [ ] P3 — `scripts/sdk-release/approval.ts` — check identity is name + `github-actions` slug + head SHA (existing behavior; `regate` gives more time to stage a same-named run, though publishing still needs a green candidates run and an artifact from its upload step)

Alberto Schiabel committed Nov 9, 2026 at 18:49 UTC bfdb8a661fdc5d9641f080b435915ab1c44dadfc
46 files changed +2554 -425
.github/workflows/docs-sdk-reference-drift.yml new
+73
@@ -0,0 +1,73 @@
1 +name: Docs - SDK reference drift
2 +
3 +# Regenerates both SDK references from the PR's sources and fails when the committed
4 +# output differs, so generator changes and stale references surface here rather than in
5 +# a release PR. It runs the generators against PR code, so it gets read-only contents
6 +# access and no secrets.
7 +on:
8 + pull_request:
9 + branches: [next]
10 + paths:
11 + - 'ts/packages/core/src/**'
12 + - 'ts/packages/core/scripts/generate-docs.ts'
13 + - 'ts/packages/core/package.json'
14 + - 'pnpm-lock.yaml'
15 + - 'python/composio/**'
16 + - 'python/scripts/generate-docs.py'
17 + - 'python/pyproject.toml'
18 + - 'uv.lock'
19 + - 'docs/content/reference/sdk-reference/**'
20 + - '.github/actions/setup-node-pnpm-bun/action.yml'
21 + - '.github/actions/setup-python-uv/action.yml'
22 + - '.github/workflows/docs-sdk-reference-drift.yml'
23 + - 'mise.toml'
24 + - 'mise.lock'
25 +
26 +concurrency:
27 + group: ${{ github.workflow }}-${{ github.ref }}
28 + cancel-in-progress: true
29 +
30 +permissions:
31 + contents: read
32 +
33 +jobs:
34 + drift:
35 + name: SDK reference drift
36 + runs-on: ubuntu-latest
37 + timeout-minutes: 15
38 + steps:
39 + - name: Checkout repository
40 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
41 + with:
42 + persist-credentials: false
43 +
44 + - name: Setup Node.js, pnpm, Bun
45 + uses: ./.github/actions/setup-node-pnpm-bun
46 + with:
47 + cache-save: 'false'
48 +
49 + - name: Setup Python and uv
50 + uses: ./.github/actions/setup-python-uv
51 + with:
52 + enable-caching: 'false'
53 +
54 + - name: Install dependencies
55 + run: pnpm install --frozen-lockfile --ignore-scripts
56 +
57 + - name: Regenerate the TypeScript reference
58 + run: pnpm --filter @composio/core generate:docs
59 +
60 + - name: Regenerate the Python reference
61 + working-directory: python
62 + run: uv run --frozen --only-group docs-reference python scripts/generate-docs.py
63 +
64 + - name: Check for drift
65 + run: |
66 + changed=$(git status --porcelain --untracked-files=all -- docs/content/reference/sdk-reference)
67 + if [[ -n "$changed" ]]; then
68 + echo "::error::The committed SDK reference is out of date with its sources."
69 + echo "$changed"
70 + git diff --stat -- docs/content/reference/sdk-reference
71 + echo "Regenerate with: pnpm --filter @composio/core generate:docs && (cd python && uv run --frozen --only-group docs-reference python scripts/generate-docs.py)"
72 + exit 1
73 + fi
.github/workflows/docs-tests.yml
+3
@@ -20,6 +20,9 @@ permissions:
20
21 jobs:
22 test:
23 + # This job installs the published SDK packages. A release PR checks its docs against the
24 + # packages it will publish instead, in the `SDK candidate docs` check.
25 + if: ${{ !startsWith(github.head_ref, 'sdk-release/batch-') }}
26 runs-on: ubuntu-latest
27 defaults:
28 run:
.github/workflows/docs-typescript-check.yml
+3
@@ -18,6 +18,9 @@ permissions:
18
19 jobs:
20 typescript-check:
21 + # This job installs the published SDK packages. A release PR checks its docs against the
22 + # packages it will publish instead, in the `SDK candidate docs` check.
23 + if: ${{ !startsWith(github.head_ref, 'sdk-release/batch-') }}
24 runs-on: ubuntu-latest
25 defaults:
26 run:
.github/workflows/sdk.release.candidates.yml
+52 -1
@@ -20,8 +20,10 @@ jobs:
20 github.repository == 'ComposioHQ/composio' &&
21 startsWith(github.event.pull_request.head.ref, 'sdk-release/batch-')
22 runs-on: ubuntu-latest
23 + timeout-minutes: 5
24 outputs:
25 languages: ${{ steps.select.outputs.languages }}
26 + channel: ${{ steps.select.outputs.channel }}
27 steps:
28 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
29 with:
@@ -36,7 +38,9 @@ jobs:
38 const languages = [...new Set(batch.plan.releases.map(release => release.language))];
39 // Languages reach shell steps through the matrix, so accept only known values.
40 if (!languages.every(language => ['typescript', 'python'].includes(language))) throw new Error('Unknown release language');
39 - appendFileSync(process.env.GITHUB_OUTPUT, `languages=${JSON.stringify(languages)}\n`);
41 + const channel = batch.plan.choices.channel ?? 'stable';
42 + if (!['stable', 'beta'].includes(channel)) throw new Error('Unknown release channel');
43 + appendFileSync(process.env.GITHUB_OUTPUT, `languages=${JSON.stringify(languages)}\nchannel=${channel}\n`);
44 JS
45
46 candidate:
@@ -44,6 +48,7 @@ jobs:
48 name: SDK candidate (${{ matrix.language }})
49 needs: select-candidates
50 runs-on: ubuntu-latest
51 + timeout-minutes: 30
52 strategy:
53 fail-fast: false
54 matrix:
@@ -91,6 +96,7 @@ jobs:
96 name: SDK candidate smoke (${{ matrix.language }})
97 needs: [select-candidates, candidate]
98 runs-on: ubuntu-latest
99 + timeout-minutes: 30
100 permissions:
101 contents: read
102 actions: read
@@ -118,3 +124,48 @@ jobs:
124 env:
125 LANGUAGE: ${{ matrix.language }}
126 run: bun scripts/sdk-release/consumers.ts "sdk-candidate/$LANGUAGE"
127 +
128 + # Type-checks and builds the docs against the packages this release publishes, not the published
129 + # ones the pull-request docs workflows install. Like the smoke job it runs third-party code with
130 + # this run's runtime token, so it has no upload step and no credentials.
131 + docs:
132 + # The release merge requires this check name to pass on the approved head of a stable release.
133 + name: SDK candidate docs
134 + needs: [select-candidates, candidate]
135 + # Runs even when the Python candidate fails, so its result still reaches the reviewers.
136 + if: ${{ !cancelled() && needs.select-candidates.outputs.channel == 'stable' }}
137 + runs-on: ubuntu-latest
138 + timeout-minutes: 45
139 + permissions:
140 + contents: read
141 + steps:
142 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
143 + with:
144 + ref: ${{ github.event.pull_request.head.sha }}
145 + persist-credentials: false
146 + - uses: ./.github/actions/setup-node-pnpm-bun
147 + with:
148 + enable-caching: 'false'
149 + - run: pnpm install --frozen-lockfile --ignore-scripts
150 + - if: contains(fromJSON(needs.select-candidates.outputs.languages), 'typescript')
151 + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
152 + with:
153 + name: sdk-candidate-typescript
154 + path: sdk-candidate/typescript
155 + - name: Install the docs against the candidate packages
156 + run: bun scripts/sdk-release/candidate-registry.ts sdk-candidate/typescript
157 + - name: Lint TypeScript
158 + working-directory: docs
159 + run: bun run lint
160 + - name: TypeScript type check
161 + working-directory: docs
162 + run: bun run types:check
163 + - name: Check TypeScript snippet and KB language-option regressions
164 + working-directory: docs
165 + run: bun test tests/static/typescript-snippets.test.ts tests/static/kb-generation.test.ts
166 + - name: Check authored TypeScript outside Twoslash build coverage
167 + working-directory: docs
168 + run: bun run check:typescript-snippets
169 + - name: Build (validates Twoslash TypeScript code blocks)
170 + working-directory: docs
171 + run: bun run build
.github/workflows/sdk.release.lint.yml
+7 -3
@@ -1,12 +1,14 @@
1 name: SDK release lint
2
3 -# Checks the release workflows before they can run: actionlint for syntax, expressions and
4 -# shell, and zizmor for security problems such as template injection, unpinned actions and
5 -# dangerous triggers. Each accepted zizmor finding is suppressed inline with its reason.
3 +# Checks the release workflows, and the reference-drift check that runs generators on PR code,
4 +# before they can run: actionlint for syntax, expressions and shell, and zizmor for security
5 +# problems such as template injection, unpinned actions and dangerous triggers. Each accepted
6 +# zizmor finding is suppressed inline with its reason.
7 on:
8 pull_request:
9 paths:
10 - '.github/workflows/sdk.release*.yml'
11 + - '.github/workflows/docs-sdk-reference-drift.yml'
12 - '.github/ISSUE_TEMPLATE/sdk-release.yml'
13 - '.github/actions/**'
14
@@ -29,9 +31,11 @@ jobs:
31 uvx --from actionlint-py==1.7.12.24 actionlint
32 -ignore 'unexpected key "queue" for "concurrency" section'
33 .github/workflows/sdk.release*.yml
34 + .github/workflows/docs-sdk-reference-drift.yml
35 - name: zizmor
36 env:
37 GH_TOKEN: ${{ github.token }}
38 run: >-
39 uvx zizmor==1.31.1 --min-severity medium --format github
40 .github/workflows/sdk.release*.yml
41 + .github/workflows/docs-sdk-reference-drift.yml
.github/workflows/sdk.release.yml
+81 -15
@@ -8,7 +8,9 @@ run-name: SDK release (${{ github.event_name }}, ${{ github.actor }})
8 # sdk.release.candidates.yml builds and smoke-tests the files on the release PR;
9 # a writer who did not request the release approves, and a person merges.
10 # 2. review when the release PR closes, the bot re-checks approval and checks, then tags the
11 -# reviewed head. A PR closed without merging is abandoned.
11 +# reviewed head. A PR closed without merging is abandoned. A `regate` dispatch
12 +# from next re-runs that gate, as next has it now, for a merged release that a
13 +# since-fixed gate bug left untagged.
14 # 3. publish the tag run uploads the reviewed files to npm and PyPI, then opens a docs PR
15 # that pins the released versions so twoslash checks against them.
16
@@ -17,6 +19,11 @@ on:
19 types: [opened]
20 workflow_dispatch:
21 inputs:
22 + action:
23 + description: request plans a release; regate re-checks and tags the merged, untagged release on next
24 + type: choice
25 + options: [request, regate]
26 + default: request
27 channel:
28 description: stable consumes the changesets; beta publishes a preview to npm next
29 type: choice
@@ -48,9 +55,10 @@ jobs:
55 plan:
56 if: >-
57 github.repository == 'ComposioHQ/composio' && github.ref == 'refs/heads/next' &&
51 - (github.event_name == 'workflow_dispatch' ||
58 + ((github.event_name == 'workflow_dispatch' && inputs.action == 'request') ||
59 (github.event_name == 'issues' && startsWith(github.event.issue.title, '[SDK release]')))
60 runs-on: ubuntu-latest
61 + timeout-minutes: 15
62 environment: sdk-release-control
63 # Queued, not replaced: a newer request never cancels one that is already waiting.
64 concurrency:
@@ -86,6 +94,7 @@ jobs:
94 needs: plan
95 if: needs.plan.outputs.batch != ''
96 runs-on: ubuntu-latest
97 + timeout-minutes: 30
98 steps:
99 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
100 with:
@@ -115,6 +124,7 @@ jobs:
124 release-pr:
125 needs: [plan, prepare]
126 runs-on: ubuntu-latest
127 + timeout-minutes: 15
128 environment: sdk-release-control
129 outputs:
130 state: ${{ steps.open.outputs.state }}
@@ -153,6 +163,7 @@ jobs:
163 needs: [plan, prepare, release-pr]
164 if: always() && needs.plan.result != 'skipped'
165 runs-on: ubuntu-latest
166 + timeout-minutes: 5
167 permissions:
168 contents: read
169 issues: write
@@ -181,7 +192,12 @@ jobs:
192 github.repository == 'ComposioHQ/composio' && github.event_name == 'pull_request_target' &&
193 startsWith(github.event.pull_request.head.ref, 'sdk-release/batch-')
194 runs-on: ubuntu-latest
195 + timeout-minutes: 15
196 environment: sdk-release-control
197 + # Shared with regate, so a re-gate and a closing release PR never tag at the same time.
198 + concurrency:
199 + group: sdk-release-tag
200 + queue: max
201 outputs:
202 issue: ${{ steps.tag.outputs.issue }}
203 state: ${{ steps.tag.outputs.state }}
@@ -207,26 +223,64 @@ jobs:
223 SDK_RELEASE_APP_SLUG: ${{ vars.SDK_RELEASE_APP_SLUG }}
224 run: bun scripts/sdk-release/batch.ts tag
225
226 + # Recovers a merged release that a gate bug left untagged, once the fix is on next. It finds the
227 + # release from the untagged plan on next, so it cannot be pointed at another PR or commit, and
228 + # applies the same gate. The new tag's push starts publishing as usual.
229 + regate:
230 + if: >-
231 + github.repository == 'ComposioHQ/composio' && github.event_name == 'workflow_dispatch' &&
232 + inputs.action == 'regate' && github.ref == 'refs/heads/next'
233 + runs-on: ubuntu-latest
234 + timeout-minutes: 15
235 + environment: sdk-release-control
236 + concurrency:
237 + group: sdk-release-tag
238 + queue: max
239 + outputs:
240 + issue: ${{ steps.regate.outputs.issue }}
241 + state: ${{ steps.regate.outputs.state }}
242 + steps:
243 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
244 + with:
245 + persist-credentials: false
246 + - uses: ./.github/actions/setup-node-pnpm-bun
247 + - run: pnpm install --frozen-lockfile --ignore-scripts
248 + # A dedicated release App, installed with only the permissions the runbook lists.
249 + - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # zizmor: ignore[github-app]
250 + id: app
251 + with:
252 + client-id: ${{ vars.SDK_RELEASE_APP_CLIENT_ID }}
253 + private-key: ${{ secrets.SDK_RELEASE_APP_PRIVATE_KEY }}
254 + owner: ComposioHQ
255 + repositories: composio
256 + - name: Re-check the merged release on next, then tag its reviewed head
257 + id: regate
258 + env:
259 + SDK_RELEASE_TOKEN: ${{ steps.app.outputs.token }}
260 + SDK_RELEASE_APP_SLUG: ${{ vars.SDK_RELEASE_APP_SLUG }}
261 + run: bun scripts/sdk-release/batch.ts regate
262 +
263 review-status:
211 - needs: tag
212 - if: always() && needs.tag.result != 'skipped'
264 + needs: [tag, regate]
265 + if: always() && (needs.tag.result != 'skipped' || needs.regate.result != 'skipped')
266 runs-on: ubuntu-latest
267 + timeout-minutes: 5
268 permissions:
269 contents: read
270 issues: write
271 steps:
272 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
273 with:
220 - ref: ${{ github.event.pull_request.base.sha }}
274 + ref: ${{ github.event.pull_request.base.sha || github.sha }}
275 persist-credentials: false
276 - uses: ./.github/actions/setup-node-pnpm-bun
277 - run: pnpm install --frozen-lockfile --ignore-scripts
278 - name: Show the review outcome on the request issue
279 env:
280 GITHUB_TOKEN: ${{ github.token }}
227 - RESULTS: '{"tag": "${{ needs.tag.result }}"}'
228 - OUTCOME: ${{ needs.tag.outputs.state }}
229 - ISSUE: ${{ needs.tag.outputs.issue }}
281 + RESULTS: '{"tag": "${{ needs.tag.result }}", "regate": "${{ needs.regate.result }}"}'
282 + OUTCOME: ${{ needs.tag.outputs.state || needs.regate.outputs.state }}
283 + ISSUE: ${{ needs.tag.outputs.issue || needs.regate.outputs.issue }}
284 run: bun scripts/sdk-release/report.ts status review
285
286 # 3. publish ---------------------------------------------------------------------------------
@@ -236,6 +290,7 @@ jobs:
290 candidates:
291 if: github.repository == 'ComposioHQ/composio' && startsWith(github.ref, 'refs/tags/sdk-release/')
292 runs-on: ubuntu-latest
293 + timeout-minutes: 15
294 permissions:
295 contents: read
296 actions: read
@@ -263,6 +318,9 @@ jobs:
318 needs: candidates
319 if: needs.candidates.outputs.typescript == 'true'
320 runs-on: ubuntu-latest
321 + # Room for the 20-minute registry waits after the upload, after the channel tag moves and in
322 + # the fresh install, so a wait that runs out names what is missing before the job times out.
323 + timeout-minutes: 75
324 environment: npm-release
325 # One npm publisher at a time, so an older retry cannot move `latest` back over a newer release.
326 concurrency:
@@ -280,7 +338,8 @@ jobs:
338 - run: pnpm install --frozen-lockfile --ignore-scripts
339 - name: Pin npm with native dist-tag OIDC support
340 run: npm install --global npm@11.21.0 --ignore-scripts --registry=https://registry.npmjs.org
283 - - name: Upload missing npm files, move the channel tag and check their provenance
341 + # Checks npm's trusted-publishing login for every planned package before uploading anything.
342 + - name: Check the npm login, upload missing npm files, move the channel tag and check their provenance
343 id: publish
344 env:
345 SDK_READ_TOKEN: ${{ github.token }}
@@ -289,15 +348,19 @@ jobs:
348 - name: Check registry signatures on a fresh install, as a user would
349 env:
350 SPECS: ${{ steps.publish.outputs.specs }}
351 + WAIT_SECONDS: ${{ steps.publish.outputs.wait_seconds }}
352 run: |
353 cd "$(mktemp -d)"
354 npm init --yes > /dev/null
295 - # The registry CDN can serve a stale package document right after publishing.
296 - for attempt in 1 2 3 4 5; do
297 - # shellcheck disable=SC2086 # one argument per package
298 - npm install --ignore-scripts --registry=https://registry.npmjs.org $SPECS && break
299 - [ "$attempt" -lt 5 ] || exit 1
300 - echo "npm install failed (attempt $attempt); retrying in 30 seconds"
355 + # The registry CDN can serve a stale package document after npm's publish-time scan, so
356 + # the install revalidates and retries for as long as the registry wait in registry-wait.ts.
357 + # shellcheck disable=SC2086 # one argument per package
358 + until npm install --prefer-online --ignore-scripts --registry=https://registry.npmjs.org $SPECS; do
359 + if [ "$SECONDS" -ge "$WAIT_SECONDS" ]; then
360 + echo "::error::npm still does not install $SPECS after ${SECONDS}s"
361 + exit 1
362 + fi
363 + echo "npm install failed after ${SECONDS}s; retrying in 30 seconds"
364 sleep 30
365 done
366 npm audit signatures
@@ -306,6 +369,7 @@ jobs:
369 needs: candidates
370 if: needs.candidates.outputs.python == 'true'
371 runs-on: ubuntu-latest
372 + timeout-minutes: 30
373 environment: pypi-release
374 permissions:
375 contents: read
@@ -351,6 +415,7 @@ jobs:
415 docs:
416 needs: publish-npm
417 runs-on: ubuntu-latest
418 + timeout-minutes: 30
419 permissions:
420 contents: read
421 steps:
@@ -406,6 +471,7 @@ jobs:
471 needs: [candidates, publish-npm, publish-pypi, docs]
472 if: always() && needs.candidates.result != 'skipped'
473 runs-on: ubuntu-latest
474 + timeout-minutes: 5
475 permissions:
476 contents: read
477 issues: write
docs/agent-guidance/context/pipelines.md
+14 -14
@@ -18,20 +18,20 @@ Reference for all GitHub Actions workflows related to docs.
18
19 ## SDK/Build Workflows
20
21 -| Workflow | File | Trigger | What it does |
22 -| ------------------------- | --------------------------- | ----------------------- | ----------------------------------------------------------------- |
23 -| **Generate SDK Docs** | `generate-sdk-docs.yml` | Manual, schedule | Generates SDK reference documentation. |
24 -| **TS Build** | `ts.build.yml` | PR changes to `ts/` | Builds TypeScript packages. |
25 -| **TS Test** | `ts.test.yml` | PR changes to `ts/` | Runs TypeScript tests. |
26 -| **TS E2E** | `ts.test-e2e.yml` | PR changes to `ts/` | Runs E2E tests (Node, Cloudflare, CLI). |
27 -| **TS Typecheck** | `ts.typecheck.yml` | PR changes to `ts/` | TypeScript type checking for SDK. |
28 -| **TS Release** | `ts.release.yml` | Push to `next`, manual | Creates Changesets release PRs and publishes TypeScript packages. |
29 -| **TS Audit** | `ts.audit.yml` | Cron | Security audit of npm dependencies. |
30 -| **Build CLI Binaries** | `build-cli-binaries.yml` | Release | Builds CLI binaries for distribution. |
31 -| **CLI Test Installation** | `cli.test-installation.yml` | PR changes to CLI | Tests CLI installation flow. |
32 -| **Python Check** | `py.check.yaml` | PR changes to `python/` | Linting and type checking for Python SDK. |
33 -| **Python Test** | `py.test.yml` | PR changes to `python/` | Runs Python tests. |
34 -| **Python Release** | `py.release.yml` | `py@*` tags, manual | Builds and publishes Python packages. |
21 +| Workflow | File | Trigger | What it does |
22 +| ------------------------- | ------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------- |
23 +| **SDK Reference Drift** | `docs-sdk-reference-drift.yml` | PR to `next` changing SDK source or generators | Regenerates both SDK references and fails if the committed output differs. |
24 +| **TS Build** | `ts.build.yml` | PR changes to `ts/` | Builds TypeScript packages. |
25 +| **TS Test** | `ts.test.yml` | PR changes to `ts/` | Runs TypeScript tests. |
26 +| **TS E2E** | `ts.test-e2e.yml` | PR changes to `ts/` | Runs E2E tests (Node, Cloudflare, CLI). |
27 +| **TS Typecheck** | `ts.typecheck.yml` | PR changes to `ts/` | TypeScript type checking for SDK. |
28 +| **TS Release** | `ts.release.yml` | Push to `next`, manual | Creates Changesets release PRs and publishes TypeScript packages. |
29 +| **TS Audit** | `ts.audit.yml` | Cron | Security audit of npm dependencies. |
30 +| **Build CLI Binaries** | `build-cli-binaries.yml` | Release | Builds CLI binaries for distribution. |
31 +| **CLI Test Installation** | `cli.test-installation.yml` | PR changes to CLI | Tests CLI installation flow. |
32 +| **Python Check** | `py.check.yaml` | PR changes to `python/` | Linting and type checking for Python SDK. |
33 +| **Python Test** | `py.test.yml` | PR changes to `python/` | Runs Python tests. |
34 +| **Python Release** | `py.release.yml` | `py@*` tags, manual | Builds and publishes Python packages. |
35
36 ## Other Workflows
37
docs/agent-guidance/context/sdk-reference.md
+15 -13
@@ -4,22 +4,24 @@ Auto-generated SDK documentation from source code.
4
5 ## TypeScript SDK
6
7 -| Item | Path |
8 -|------|------|
9 -| Source | `ts/packages/core/src/models/*.ts` (JSDoc comments) |
10 -| Generator | `ts/packages/core/scripts/generate-docs.ts` |
11 -| Output | `content/reference/sdk-reference/typescript/` |
12 -| Regenerate | `pnpm --filter @composio/core generate:docs` |
7 +| Item | Path |
8 +| ---------- | --------------------------------------------------- |
9 +| Source | `ts/packages/core/src/models/*.ts` (JSDoc comments) |
10 +| Generator | `ts/packages/core/scripts/generate-docs.ts` |
11 +| Output | `content/reference/sdk-reference/typescript/` |
12 +| Regenerate | `pnpm --filter @composio/core generate:docs` |
13
14 ## Python SDK
15
16 -| Item | Path |
17 -|------|------|
18 -| Source | `python/composio/**/*.py` (docstrings) |
19 -| Generator | `python/scripts/generate-docs.py` (uses griffe) |
20 -| Output | `content/reference/sdk-reference/python/` |
21 -| Regenerate | `cd python && uv run --with griffe python scripts/generate-docs.py` |
16 +| Item | Path |
17 +| ---------- | ----------------------------------------------------------------------------------------------------------- |
18 +| Source | `python/composio/**/*.py` (docstrings) |
19 +| Generator | `python/scripts/generate-docs.py` (griffe, pinned in the `docs-reference` group in `python/pyproject.toml`) |
20 +| Output | `content/reference/sdk-reference/python/` |
21 +| Regenerate | `cd python && uv run --frozen --only-group docs-reference python scripts/generate-docs.py` |
22
23 ## CI Integration
24
25 -The SDK release workflow (`.github/workflows/sdk.release.yml`) regenerates both references in each release PR, so the published reference always matches the released packages.
25 +On PRs to `next` that change either SDK source or generator, `.github/workflows/docs-sdk-reference-drift.yml` regenerates both references and fails if the committed output differs. Regenerate with the commands above and commit the result.
26 +
27 +The SDK release workflow (`.github/workflows/sdk.release.yml`) also regenerates both references in each release PR, so the published reference always matches the released packages.
docs/content/docs/using-composio-skill.mdx
+1 -1
@@ -33,7 +33,7 @@ The skill routes the agent based on what you are building:
33 | Add app integrations to a product | Composio SDK and sessions |
34 | Use apps from your own coding agent | Agent plugin, CLI, or MCP |
35 | Add Composio to an existing MCP client | Composio Connect |
36 -| Ask the user before tools run | [Approvals](/docs/approvals) |
36 +| Ask the user before tools run | [Approvals](/docs/governance/approvals) |
37 | Block risky tool calls, sensitive results, or prompt injection | [Firewall](/docs/firewall) |
38 | Use tools from your own remote MCP server | [Custom MCP](/docs/extending-sessions/custom-mcp) |
39 | Diagnose a connection or tool-call error | Current docs and public support knowledge |
docs/scripts/generate-sdk-release-notes.ts
+8 -1
@@ -57,7 +57,14 @@ const LANGUAGE_DOCS: Record<
57 label: () => 'Python `composio`',
58 reference: {
59 command: 'uv',
60 - args: ['run', '--with', 'griffe', 'python', 'scripts/generate-docs.py'],
60 + args: [
61 + 'run',
62 + '--frozen',
63 + '--only-group',
64 + 'docs-reference',
65 + 'python',
66 + 'scripts/generate-docs.py',
67 + ],
68 directory: 'python',
69 },
70 },
python/docs/release.md
+1 -1
@@ -4,7 +4,7 @@ Request a stable Python release through the shared [SDK release procedure](../..
4
5 Public Python SDK/provider changes include a changeset targeting the private `@composio/python-sdk` marker. Core and supported providers form one stable train. The bot updates the version mirrors and `uv.lock` and opens one release PR. Its `SDK candidate (python)` check builds the wheels and sdists; `SDK candidate smoke (python)` installs them in a clean venv and tests the new core with the latest published providers. A repository writer who did not request the release approves the head, and a person merges it. The tag run publishes those exact files through the tag-only `pypi-release` identity.
6
7 -If publishing fails, choose **Re-run failed jobs** on the tag run within 30 days of the candidate build. After that, add a changeset for `@composio/python-sdk` and request a new release; the train moves to the next version.
7 +If publishing fails, choose **Re-run failed jobs** on the tag run within 30 days of the candidate build. After that, add a changeset for `@composio/python-sdk` and request a new release; the train moves to the next version. If the merged release was never tagged, follow the recovery table in the [SDK release procedure](../../ts/docs/internal/release.md#recover-a-failed-release).
8
9 For local packaging checks, run from `python/`:
10
python/pyproject.toml
+6
@@ -69,6 +69,12 @@ dev = [
69 docs-snippets = [
70 "mypy==2.3.1",
71 ]
72 +# `scripts/generate-docs.py` runs with only this group, so the SDK reference
73 +# that CI checks for drift and the one release preparation writes come from
74 +# the same generator version.
75 +docs-reference = [
76 + "griffe==2.3.0",
77 +]
78 # The release build installs only this group, from uv.lock, and builds with
79 # `--no-isolation` so no unlocked build backend is fetched at release time.
80 # Pinned exactly; only move to releases at least three days old, matching
python/scripts/README.md
+2 -2
@@ -6,7 +6,7 @@ Generates MDX reference docs from Python source using griffe.
6
7 ```bash
8 cd python
9 -uv run --with griffe python scripts/generate-docs.py
9 +uv run --frozen --only-group docs-reference python scripts/generate-docs.py
10 ```
11
12 ## How it works
@@ -23,4 +23,4 @@ uv run --with griffe python scripts/generate-docs.py
23
24 ## CI
25
26 -`.github/workflows/generate-sdk-docs.yml` triggers on changes to `python/composio/**` and opens a PR with updated docs.
26 +`.github/workflows/docs-sdk-reference-drift.yml` regenerates the reference on PRs to `next` that change `python/composio/**` or this generator, and fails if the committed output differs. `griffe` is pinned in the `docs-reference` dependency group in `python/pyproject.toml`.
python/scripts/generate-docs.py
+5 -2
@@ -5,7 +5,7 @@ Python SDK Documentation Generator
5 Generates MDX documentation from Python source code using griffe.
6 Output is written to the docs content directory.
7
8 -Run: cd python && uv run --with griffe python scripts/generate-docs.py
8 +Run: cd python && uv run --frozen --only-group docs-reference python scripts/generate-docs.py
9 """
10
11 from __future__ import annotations
@@ -32,7 +32,10 @@ def load_griffe() -> Any:
32 try:
33 import griffe as griffe_module
34 except ImportError:
35 - print("Error: griffe not installed. Run: pip install griffe")
35 + print(
36 + "Error: griffe not installed. Run: "
37 + "uv run --frozen --only-group docs-reference python scripts/generate-docs.py"
38 + )
39 raise SystemExit(1)
40 _griffe = griffe_module
41 return _griffe
scripts/sdk-release/approval.ts
+17 -13
@@ -1,6 +1,7 @@
1 import { Effect, Option, Schema, Stream } from 'effect';
2 import {
3 CONTENT_CONCURRENCY,
4 + PositiveInt,
5 REPOSITORY_PATH,
6 Sha,
7 fileAt,
@@ -8,7 +9,7 @@ import {
9 paginateArray,
10 request,
11 } from './github';
11 -import { Pull, isReleasePull, releaseBranch } from './release-pr';
12 +import { PullDetail, isReleasePull, releaseBranch } from './release-pr';
13 import { ensure, fail } from './runtime';
14 import { BATCH_PATH, ReleaseBatch, batchLanguages, channelOf } from './source';
15
@@ -51,6 +52,7 @@ const CollaboratorPermission = Schema.Struct({ permission: Schema.String });
52 const CheckRuns = Schema.Struct({
53 check_runs: Schema.Array(
54 Schema.Struct({
55 + id: PositiveInt,
56 name: Schema.String,
57 head_sha: Sha,
58 app: Schema.NullOr(Schema.Struct({ slug: Schema.String })),
@@ -99,7 +101,7 @@ const reviewsWithPermissions = (number: number) =>
101 /** A release PR into next and the plan committed on its head. */
102 export const readReleasePull = (number: number) =>
103 Effect.gen(function* () {
102 - const pull = yield* request('GET', `${REPOSITORY_PATH}/pulls/${number}`, Pull);
104 + const pull = yield* request('GET', `${REPOSITORY_PATH}/pulls/${number}`, PullDetail);
105 yield* ensure(
106 pull.base.ref === 'next' && isReleasePull(pull),
107 'Expected an SDK release PR into protected next'
@@ -145,7 +147,7 @@ export const isReleaseAppCommit = (sha: string, batch: ReleaseBatch, appSlug: st
147 );
148 });
149
148 -export const isReleaseAppHead = (pull: Pull, batch: ReleaseBatch, appSlug: string) =>
150 +export const isReleaseAppHead = (pull: PullDetail, batch: ReleaseBatch, appSlug: string) =>
151 isReleaseAppCommit(pull.head.sha, batch, appSlug);
152
153 const IssueEvent = Schema.Struct({ event: Schema.String, commit_id: Schema.NullOr(Sha) });
@@ -166,7 +168,7 @@ export const mergeCommitOf = (number: number) =>
168 * Anyone with write access can push a `sdk-release/batch-*` branch, so its plan cannot pick the
169 * issue the bot comments on, labels and closes.
170 */
169 -export const trustedIssue = (pull: Pull, batch: ReleaseBatch, appSlug: string) =>
171 +export const trustedIssue = (pull: PullDetail, batch: ReleaseBatch, appSlug: string) =>
172 Effect.map(isReleaseAppHead(pull, batch, appSlug), trusted =>
173 trusted ? Option.some(batch.issue) : Option.none<number>()
174 );
@@ -178,7 +180,7 @@ export const trustedIssue = (pull: Pull, batch: ReleaseBatch, appSlug: string) =
180 * - a writer other than the author and the requester approved that head;
181 * - the candidate build and smoke checks passed on it, and the docs check for a stable release.
182 */
181 -export const verifyReleaseGate = (pull: Pull, batch: ReleaseBatch, appSlug: string) =>
183 +export const verifyReleaseGate = (pull: PullDetail, batch: ReleaseBatch, appSlug: string) =>
184 Effect.gen(function* () {
185 yield* ensure(
186 yield* isReleaseAppHead(pull, batch, appSlug),
@@ -201,14 +203,16 @@ export const verifyReleaseGate = (pull: Pull, batch: ReleaseBatch, appSlug: stri
203 body => body.check_runs
204 )
205 );
204 - const passed = (name: string) =>
205 - checks.some(
206 - check =>
207 - check.name === name &&
208 - check.head_sha === pull.head.sha &&
209 - check.app?.slug === 'github-actions' &&
210 - check.conclusion === 'success'
211 - );
206 + // A re-run adds a newer check run under the same name; only the newest one counts.
207 + const latest = new Map<string, (typeof checks)[number]>();
208 + for (const check of checks)
209 + if (
210 + check.head_sha === pull.head.sha &&
211 + check.app?.slug === 'github-actions' &&
212 + check.id > (latest.get(check.name)?.id ?? 0)
213 + )
214 + latest.set(check.name, check);
215 + const passed = (name: string) => latest.get(name)?.conclusion === 'success';
216 for (const language of batchLanguages(batch))
217 for (const check of [`SDK candidate (${language})`, `SDK candidate smoke (${language})`])
218 yield* ensure(passed(check), `Missing green final-head check: ${check}`);
scripts/sdk-release/artifacts.ts
+3 -1
@@ -60,6 +60,8 @@ export const ActionArtifact = Schema.Struct({
60 });
61 export type CandidateArtifact = typeof ActionArtifact.Type;
62
63 +const ArtifactsPage = Schema.Struct({ artifacts: Schema.Array(ActionArtifact) });
64 +
65 export const normalizeArtifactDigest = (value: unknown) =>
66 Effect.gen(function* () {
67 const digest = yield* Schema.decodeUnknownEffect(Schema.String)(value);
@@ -136,7 +138,7 @@ export const originalCandidates = (run: number) =>
138 Stream.runCollect(
139 paginate(
140 `${REPOSITORY_PATH}/actions/runs/${run}/artifacts`,
139 - Schema.Struct({ artifacts: Schema.Array(ActionArtifact) }),
141 + ArtifactsPage,
142 body => body.artifacts
143 )
144 );
scripts/sdk-release/batch.ts
+89 -22
@@ -21,7 +21,8 @@ import {
21 } from './github';
22 import { createSdkReleasePlan, type SdkReleasePlan } from './plan';
23 import {
24 - Pull,
24 + PullDetail,
25 + PullListItem,
26 isReleasePull,
27 releaseBranch,
28 releasePullBody,
@@ -45,9 +46,9 @@ import {
46 releaseTag,
47 validateBatchDiff,
48 } from './source';
48 -import { ReleaseState } from './state';
49 +import { RECOVERY_RUNBOOK, ReleaseState } from './state';
50
50 -const Commit = Schema.Struct({
51 +const GitCommit = Schema.Struct({
52 sha: Sha,
53 tree: Schema.Struct({ sha: Sha }),
54 parents: Schema.Array(Schema.Struct({ sha: Sha })),
@@ -57,23 +58,33 @@ const CreatedRef = Schema.Struct({ ref: Schema.String });
58 /** The open release PR into next, if any. Only one release runs at a time. */
59 export const activeRelease = paginateArray(
60 `${REPOSITORY_PATH}/pulls?state=open&base=next`,
60 - Pull
61 + PullListItem
62 ).pipe(Stream.filter(isReleasePull), Stream.runHead);
63
63 -/**
64 - * The id of a release plan committed on `sha` whose tag was never created: its release PR merged
65 - * but failed the gate, or its tag job has not finished. Only the id is read, so older plan shapes
66 - * still decode.
67 - */
68 -const untaggedRelease = (sha: string) =>
64 +/** The id of the release plan committed on `sha`. Only the id is read, so older plan shapes still decode. */
65 +const committedRelease = (sha: string) =>
66 Effect.gen(function* () {
67 const committed = yield* fileAt(BATCH_PATH, sha);
68 if (Option.isNone(committed)) return Option.none<string>();
69 const { id } = yield* Schema.decodeUnknownEffect(
70 Schema.fromJsonString(Schema.Struct({ id: RunId }))
71 )(committed.value);
75 - const tag = yield* requestOptional(`${REPOSITORY_PATH}/git/ref/tags/${releaseTag(id)}`, TagRef);
76 - return Option.isNone(tag) ? Option.some(id) : Option.none<string>();
72 + return Option.some(id);
73 + });
74 +
75 +/**
76 + * The id of a release plan committed on `sha` whose tag was never created: its release PR merged
77 + * but failed the gate, or its tag job has not finished.
78 + */
79 +const untaggedRelease = (sha: string) =>
80 + Effect.gen(function* () {
81 + const id = yield* committedRelease(sha);
82 + if (Option.isNone(id)) return id;
83 + const tag = yield* requestOptional(
84 + `${REPOSITORY_PATH}/git/ref/tags/${releaseTag(id.value)}`,
85 + TagRef
86 + );
87 + return Option.isNone(tag) ? id : Option.none<string>();
88 });
89
90 // 1. request -----------------------------------------------------------------------------------
@@ -184,7 +195,7 @@ const commitReleaseBranch = (batch: ReleaseBatch, patch: ReleasePatch) =>
195 const source = yield* request(
196 'GET',
197 `${REPOSITORY_PATH}/git/commits/${batch.inputBase}`,
187 - Commit
198 + GitCommit
199 );
200 const blobs = yield* Effect.forEach(
201 patch.files,
@@ -274,7 +285,7 @@ export const openReleasePull = (cwd: string, planned: ReleaseBatch, value: unkno
285 const outputs = yield* releaseOutputs(cwd, batch);
286 yield* validateBatchDiff(patch.files, batch, outputs);
287 const branch = yield* commitReleaseBranch(batch, patch);
277 - const pull = yield* request('POST', `${REPOSITORY_PATH}/pulls`, Pull, {
288 + const pull = yield* request('POST', `${REPOSITORY_PATH}/pulls`, PullDetail, {
289 title: releasePullTitle(batch),
290 head: branch,
291 base: 'next',
@@ -291,7 +302,7 @@ export const openReleasePull = (cwd: string, planned: ReleaseBatch, value: unkno
302 * a GitHub or transport error fails the job so "Re-run failed jobs" retries it. GitHub records the
303 * head and the squash commit separately, so a single-parent squash need not list the head.
304 */
294 -export const authorizeSourceTag = (pull: Pull, batch: ReleaseBatch, appSlug: string) =>
305 +export const authorizeSourceTag = (pull: PullDetail, batch: ReleaseBatch, appSlug: string) =>
306 Effect.gen(function* () {
307 if (!pull.merged) return ReleaseState.make({ _tag: 'Abandoned', pull: pull.html_url });
308 const verdict = yield* verifyReleaseGate(pull, batch, appSlug).pipe(
@@ -301,14 +312,14 @@ export const authorizeSourceTag = (pull: Pull, batch: ReleaseBatch, appSlug: str
312 if (Option.isSome(verdict)) {
313 yield* commentIssue(
314 pull.number,
304 - `This release PR merged, but it failed the release gate, so nothing was tagged or published.\n\nReason: ${verdict.value}\n\nRevert it on \`next\`, then request the release again.`
315 + `This release PR merged, but it failed the release gate, so nothing was tagged or published.\n\nReason: ${verdict.value}\n\nRevert it on \`next\`, then request the release again. If the gate itself was wrong, fix it on \`next\` and dispatch **SDK release** with action \`regate\` instead: ${RECOVERY_RUNBOOK}`
316 );
317 return ReleaseState.make({ _tag: 'Refused', pull: pull.html_url, reason: verdict.value });
318 }
319 const merged = yield* request(
320 'GET',
321 `${REPOSITORY_PATH}/git/commits/${yield* mergeCommitOf(pull.number)}`,
311 - Commit
322 + GitCommit
323 );
324 yield* ensure(
325 merged.parents.some(parent => parent.sha === pull.head.sha) || merged.parents.length === 1,
@@ -331,6 +342,54 @@ export const authorizeSourceTag = (pull: Pull, batch: ReleaseBatch, appSlug: str
342 return ReleaseState.make({ _tag: 'Tagged', tag });
343 });
344
345 +// 4. regate ------------------------------------------------------------------------------------
346 +
347 +/**
348 + * The merged release PR behind the plan `next` carries, for re-gating with the gate as `next`
349 + * has it now: the recovery for a release that a since-fixed gate bug left untagged. The plan
350 + * names the release and its branch names the PR, so nobody can point this at another PR or
351 + * commit, and `authorizeSourceTag` then applies exactly the gate and tag a closing PR gets.
352 + */
353 +export const releaseToRegate = (actor: string, sourceSha: string) =>
354 + Effect.gen(function* () {
355 + yield* requireActiveMember(actor);
356 + const id = yield* committedRelease(sourceSha);
357 + if (Option.isNone(id)) return yield* fail('Nothing to re-gate: `next` carries no release plan');
358 + const branch = releaseBranch(id.value);
359 + const closed = yield* Stream.runCollect(
360 + paginateArray(
361 + `${REPOSITORY_PATH}/pulls?state=closed&base=next&head=${encodeURIComponent(`ComposioHQ:${branch}`)}`,
362 + PullListItem
363 + )
364 + );
365 + const pulls = yield* Effect.forEach(
366 + closed.filter(pull => isReleasePull(pull) && pull.head.ref === branch),
367 + pull => readReleasePull(pull.number)
368 + );
369 + // A re-run of the release-PR job can leave an older closed PR on the same branch.
370 + const [release] = pulls.toSorted(
371 + (a, b) => Number(b.pull.merged) - Number(a.pull.merged) || b.pull.number - a.pull.number
372 + );
373 + if (!release) return yield* fail(`Nothing to re-gate: no closed release PR from ${branch}`);
374 + return release;
375 + });
376 +
377 +/**
378 + * Tags a release the gate left untagged. A release already tagged on its reviewed head is left
379 + * alone, so a release published under an older gate is never judged by today's.
380 + */
381 +export const regateRelease = (pull: PullDetail, batch: ReleaseBatch, appSlug: string) =>
382 + Effect.gen(function* () {
383 + const tag = releaseTag(batch.id);
384 + const existing = yield* requestOptional(`${REPOSITORY_PATH}/git/ref/tags/${tag}`, TagRef);
385 + if (Option.isNone(existing)) return yield* authorizeSourceTag(pull, batch, appSlug);
386 + yield* ensure(
387 + existing.value.object.type === 'commit' && existing.value.object.sha === pull.head.sha,
388 + 'Publication source tag already points to another source'
389 + );
390 + return ReleaseState.make({ _tag: 'Tagged', tag });
391 + });
392 +
393 // entry point ----------------------------------------------------------------------------------
394
395 const Environment = Config.all({
@@ -368,7 +427,7 @@ const outputIssue = (env: Environment, issue: Option.Option<number>) =>
427 const outputState = (env: Environment, state: ReleaseState) =>
428 appendFile(env.outputPath, `state=${JSON.stringify(state)}\n`);
429
371 -const MODES: Record<'plan' | 'release-pr' | 'tag', Mode> = {
430 +const MODES: Record<'plan' | 'release-pr' | 'tag' | 'regate', Mode> = {
431 plan: (env: Environment, event: unknown, envelope: typeof EventEnvelope.Type) =>
432 Effect.gen(function* () {
433 const cwd = (yield* Path.Path).resolve('.');
@@ -414,14 +473,22 @@ const MODES: Record<'plan' | 'release-pr' | 'tag', Mode> = {
473 yield* outputIssue(env, issue);
474 yield* outputState(env, yield* authorizeSourceTag(pull, batch, appSlug));
475 }),
476 + regate: (env: Environment, _event: unknown, envelope: typeof EventEnvelope.Type) =>
477 + Effect.gen(function* () {
478 + const appSlug = yield* Config.String('SDK_RELEASE_APP_SLUG');
479 + const { pull, batch } = yield* releaseToRegate(envelope.sender.login, env.sha);
480 + const issue = yield* trustedIssue(pull, batch, appSlug);
481 + yield* outputIssue(env, issue);
482 + yield* outputState(env, yield* regateRelease(pull, batch, appSlug));
483 + }),
484 };
485
419 -/** `batch.ts plan`, `batch.ts release-pr <patch>`, or `batch.ts tag`. */
486 +/** `batch.ts plan`, `batch.ts release-pr <patch>`, `batch.ts tag`, or `batch.ts regate`. */
487 const main = Effect.gen(function* () {
488 const [argument] = yield* (yield* Stdio.Stdio).args;
422 - const mode = yield* Schema.decodeUnknownEffect(Schema.Literals(['plan', 'release-pr', 'tag']))(
423 - argument
424 - );
489 + const mode = yield* Schema.decodeUnknownEffect(
490 + Schema.Literals(['plan', 'release-pr', 'tag', 'regate'])
491 + )(argument);
492 const env = yield* Environment;
493 const event = yield* readJson(Schema.Unknown, env.eventPath);
494 const envelope = yield* Schema.decodeUnknownEffect(EventEnvelope)(event);
scripts/sdk-release/candidate-registry.ts new
+269
@@ -0,0 +1,269 @@
1 +import * as BunHttpServer from '@effect/platform-bun/BunHttpServer';
2 +import { Effect, FileSystem, Option, Path, Schema, Stdio } from 'effect';
3 +import { Digest } from 'effect/crypto';
4 +import { Base64 } from 'effect/encoding';
5 +import { HttpClient, HttpServer, HttpServerRequest, HttpServerResponse } from 'effect/http';
6 +import { PackedManifest, tarballName } from './candidates';
7 +import { readVerifiedCandidate } from './consumers';
8 +import { NPM_REGISTRY } from './lanes';
9 +import {
10 + ensure,
11 + fail,
12 + formatJson,
13 + readJson,
14 + run,
15 + runMain,
16 + withoutReleaseTokens,
17 + writeFile,
18 +} from './runtime';
19 +import { BATCH_PATH, ReleaseBatch } from './source';
20 +
21 +type PlannedPackage = Pick<ReleaseBatch['plan']['releases'][number], 'name' | 'newVersion'>;
22 +
23 +export interface CandidatePackage {
24 + readonly manifest: typeof PackedManifest.Type;
25 + readonly bytes: Uint8Array;
26 + readonly integrity: string;
27 +}
28 +
29 +/**
30 + * Reads the planned packages from a downloaded TypeScript candidate. Every file is checked
31 + * against the candidate manifest first, so the registry never serves bytes the candidate job did
32 + * not build.
33 + */
34 +export const loadCandidatePackages = (
35 + candidates: string,
36 + releases: ReadonlyArray<PlannedPackage>
37 +) =>
38 + Effect.gen(function* () {
39 + const digest = yield* Digest.Digest;
40 + const { manifest, files } = yield* readVerifiedCandidate(candidates);
41 + yield* ensure(manifest.language === 'typescript', 'Expected the TypeScript candidate');
42 + return yield* Effect.forEach(releases, release =>
43 + Effect.gen(function* () {
44 + const file = tarballName(release.name, release.newVersion);
45 + const bytes = files.get(file);
46 + if (!bytes) return yield* fail(`Missing candidate tarball: ${file}`);
47 + const packed = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(PackedManifest))(
48 + yield* run('tar', ['-xOf', `${candidates}/${file}`, 'package/package.json'], {
49 + env: withoutReleaseTokens,
50 + })
51 + );
52 + yield* ensure(
53 + packed.name === release.name && packed.version === release.newVersion,
54 + `Candidate ${file} does not contain ${release.name}@${release.newVersion}`
55 + );
56 + const integrity = `sha512-${Base64.encode(yield* digest.digest(Digest.sha512, bytes))}`;
57 + return { manifest: packed, bytes, integrity } satisfies CandidatePackage;
58 + })
59 + );
60 + });
61 +
62 +/** The npm package a registry path names: `@scope/name/-/name-1.0.0.tgz` names `@scope/name`. */
63 +const packageOf = (path: string) => {
64 + const [first = '', second = ''] = path.split('/');
65 + return first.startsWith('@') ? `${first}/${second}` : first;
66 +};
67 +
68 +/**
69 + * Starts an npm registry on localhost for the current scope. It serves the planned packages from
70 + * their candidate tarballs, at the candidate version only, and proxies every other package to
71 + * `upstream`. A planned package never falls through to `upstream`, so no copy can resolve to a
72 + * published version. Returns the registry URL.
73 + */
74 +export const serveCandidateRegistry = (
75 + packages: ReadonlyArray<CandidatePackage>,
76 + upstream: string = NPM_REGISTRY
77 +) =>
78 + Effect.gen(function* () {
79 + const client = yield* HttpClient.HttpClient;
80 + const server = yield* BunHttpServer.make({ port: 0, hostname: '127.0.0.1' });
81 + const origin = HttpServer.formatAddress(server.address);
82 + const packuments = new Map<string, unknown>();
83 + const tarballs = new Map<string, Uint8Array>();
84 + for (const { manifest, bytes, integrity } of packages) {
85 + const tarball = `${manifest.name}/-/${manifest.name.split('/').at(-1)}-${manifest.version}.tgz`;
86 + tarballs.set(tarball, bytes);
87 + packuments.set(manifest.name, {
88 + name: manifest.name,
89 + 'dist-tags': { latest: manifest.version },
90 + versions: {
91 + [manifest.version]: { ...manifest, dist: { tarball: `${origin}/${tarball}`, integrity } },
92 + },
93 + });
94 + }
95 + yield* server.serve(
96 + Effect.gen(function* () {
97 + const request = yield* HttpServerRequest.HttpServerRequest;
98 + const url = new URL(request.url, origin);
99 + // Clients spell a scoped packument as `@scope%2fname` or `@scope/name`.
100 + const path = decodeURIComponent(url.pathname).slice(1);
101 + const packument = packuments.get(path);
102 + if (packument) return HttpServerResponse.jsonUnsafe(packument);
103 + const tarball = tarballs.get(path);
104 + if (tarball)
105 + return HttpServerResponse.uint8Array(tarball, {
106 + contentType: 'application/octet-stream',
107 + });
108 + if (request.method !== 'GET' || packuments.has(packageOf(path)))
109 + return HttpServerResponse.empty({ status: 404 });
110 + const response = yield* client.get(`${upstream}${url.pathname}${url.search}`, {
111 + headers: { accept: request.headers.accept ?? '*/*' },
112 + });
113 + return HttpServerResponse.uint8Array(new Uint8Array(yield* response.arrayBuffer), {
114 + status: response.status,
115 + contentType: response.headers['content-type'],
116 + });
117 + })
118 + );
119 + return origin;
120 + });
121 +
122 +const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies'] as const;
123 +const Dependencies = Schema.optionalKey(Schema.Record(Schema.String, Schema.String));
124 +const DocsManifest = Schema.StructWithRest(
125 + Schema.Struct({
126 + dependencies: Dependencies,
127 + devDependencies: Dependencies,
128 + optionalDependencies: Dependencies,
129 + overrides: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
130 + }),
131 + [Schema.Record(Schema.String, Schema.Unknown)]
132 +);
133 +
134 +/**
135 + * Pins the planned packages to their candidate versions in this checkout's docs manifest, as
136 + * direct dependencies and as overrides for every nested copy. The committed docs pins name
137 + * published versions; this job-local edit is never committed. Returns the planned packages the
138 + * docs depend on directly.
139 + */
140 +export const pinCandidateVersions = (
141 + manifestPath: string,
142 + releases: ReadonlyArray<PlannedPackage>
143 +) =>
144 + Effect.gen(function* () {
145 + const manifest = yield* readJson(DocsManifest, manifestPath);
146 + const pins = Object.fromEntries(releases.map(release => [release.name, release.newVersion]));
147 + const direct = releases
148 + .map(release => release.name)
149 + .filter(name => DEPENDENCY_FIELDS.some(field => manifest[field]?.[name] !== undefined));
150 + const pinned: Record<string, unknown> = {
151 + ...manifest,
152 + overrides: { ...manifest.overrides, ...pins },
153 + };
154 + for (const field of DEPENDENCY_FIELDS) {
155 + const dependencies = manifest[field];
156 + if (!dependencies) continue;
157 + pinned[field] = Object.fromEntries(
158 + Object.entries(dependencies).map(([name, range]) => [name, pins[name] ?? range])
159 + );
160 + }
161 + yield* writeFile(manifestPath, formatJson(pinned));
162 + return direct;
163 + });
164 +
165 +const Versioned = Schema.Struct({ version: Schema.String });
166 +
167 +const installedCopies = (nodeModules: string, names: ReadonlySet<string>) =>
168 + Effect.gen(function* () {
169 + const fs = yield* FileSystem.FileSystem;
170 + const path = yield* Path.Path;
171 + const copies: { name: string; directory: string; version: string }[] = [];
172 + const pending = [nodeModules];
173 + for (let directory = pending.pop(); directory !== undefined; directory = pending.pop()) {
174 + const info = yield* Effect.option(fs.stat(directory));
175 + if (Option.isNone(info) || info.value.type !== 'Directory') continue;
176 + for (const entry of yield* fs.readDirectory(directory)) {
177 + // The isolated linker keeps each package under `.bun/<name>@<version>/node_modules`.
178 + if (entry === '.bun') {
179 + for (const store of yield* fs.readDirectory(path.join(directory, entry)))
180 + pending.push(path.join(directory, entry, store, 'node_modules'));
181 + continue;
182 + }
183 + const packageNames = entry.startsWith('@')
184 + ? (yield* fs.readDirectory(path.join(directory, entry))).map(
185 + scoped => `${entry}/${scoped}`
186 + )
187 + : [entry];
188 + for (const name of packageNames) {
189 + const packageDirectory = path.join(directory, name);
190 + if (names.has(name))
191 + copies.push({
192 + name,
193 + directory: packageDirectory,
194 + version: (yield* readJson(Versioned, path.join(packageDirectory, 'package.json')))
195 + .version,
196 + });
197 + pending.push(path.join(packageDirectory, 'node_modules'));
198 + }
199 + }
200 + }
201 + return copies;
202 + });
203 +
204 +/**
205 + * Fails unless every installed copy of a planned package is its candidate version and each
206 + * planned package in `required` is installed at all.
207 + */
208 +export const assertCandidateVersions = (
209 + nodeModules: string,
210 + releases: ReadonlyArray<PlannedPackage>,
211 + required: ReadonlyArray<string>
212 +) =>
213 + Effect.gen(function* () {
214 + const versions = new Map(releases.map(release => [release.name, release.newVersion]));
215 + const copies = yield* installedCopies(nodeModules, new Set(versions.keys()));
216 + const problems = [
217 + ...required
218 + .filter(name => !copies.some(copy => copy.name === name))
219 + .map(name => `${name} is not installed`),
220 + ...copies
221 + .filter(copy => copy.version !== versions.get(copy.name))
222 + .map(copy => `${copy.directory} is ${copy.version}, not ${versions.get(copy.name)}`),
223 + ];
224 + yield* ensure(
225 + problems.length === 0,
226 + `The docs did not install the candidate packages:\n${problems.join('\n')}`
227 + );
228 + });
229 +
230 +const bun = (docs: string, args: ReadonlyArray<string>, env: Record<string, string> = {}) =>
231 + run('bun', args, { cwd: docs, env: { ...withoutReleaseTokens, ...env }, output: 'inherit' });
232 +
233 +/**
234 + * Installs the docs dependencies for a stable release PR. Without a TypeScript release, the
235 + * committed lock is installed from npm as is. Otherwise the planned packages come from the
236 + * candidate through a job-local registry, every other package through its npm proxy, and every
237 + * installed copy of a planned package must be its candidate version.
238 + */
239 +export const installCandidateDocs = (docs: string, batch: ReleaseBatch, candidates: string) =>
240 + Effect.scoped(
241 + Effect.gen(function* () {
242 + const fs = yield* FileSystem.FileSystem;
243 + const path = yield* Path.Path;
244 + const npm = batch.plan.releases.filter(release => release.language === 'typescript');
245 + if (npm.length === 0) return yield* bun(docs, ['install', '--frozen-lockfile']);
246 + const packages = yield* loadCandidatePackages(candidates, npm);
247 + const registry = yield* serveCandidateRegistry(packages);
248 + const direct = yield* pinCandidateVersions(path.join(docs, 'package.json'), npm);
249 + // A fresh cache, so no planned package is reused from an earlier install.
250 + const cache = yield* fs.makeTempDirectoryScoped({ prefix: 'sdk-candidate-docs-cache-' });
251 + yield* bun(docs, ['install'], {
252 + NPM_CONFIG_REGISTRY: registry,
253 + BUN_INSTALL_CACHE_DIR: cache,
254 + });
255 + yield* assertCandidateVersions(path.join(docs, 'node_modules'), npm, direct);
256 + })
257 + );
258 +
259 +/** `candidate-registry.ts <candidate-dir>` installs the docs against a stable release's candidate. */
260 +const main = Effect.gen(function* () {
261 + const path = yield* Path.Path;
262 + const [candidates] = yield* Schema.decodeUnknownEffect(Schema.Tuple([Schema.String]))(
263 + yield* (yield* Stdio.Stdio).args
264 + );
265 + const batch = yield* readJson(ReleaseBatch, BATCH_PATH);
266 + yield* installCandidateDocs(path.resolve('docs'), batch, path.resolve(candidates));
267 +});
268 +
269 +if (import.meta.main) runMain(main);
scripts/sdk-release/candidates.ts
+9 -3
@@ -43,7 +43,7 @@ import {
43 } from './runtime';
44 import { BATCH_PATH, ReleaseBatch, batchLanguages, channelOf, releaseTag } from './source';
45
46 -const PackedManifest = Schema.StructWithRest(
46 +export const PackedManifest = Schema.StructWithRest(
47 Schema.Struct({ name: Schema.String, version: Schema.String }),
48 [Schema.Record(Schema.String, Schema.Unknown)]
49 );
@@ -166,6 +166,11 @@ const isSourceTag = (ref: string) => ref.startsWith('refs/tags/sdk-release/');
166 const CANDIDATES_WORKFLOW = 'sdk.release.candidates.yml';
167 const CANDIDATES_WORKFLOW_PATH = `.github/workflows/${CANDIDATES_WORKFLOW}`;
168
169 +const WorkflowRuns = Schema.Struct({ workflow_runs: Schema.Array(ReleaseRun) });
170 +
171 +/** GitHub reports step and artifact times to the second, so an artifact can land on either boundary second. */
172 +const TIMESTAMP_SLACK_MS = 1_000;
173 +
174 /** The release-PR build step that uploads the candidate artifact. */
175 const UPLOAD_STEP = 'Retain candidate bytes for publication';
176
@@ -200,7 +205,8 @@ const requireCreatedDuring = (
205 );
206 const created = Date.parse(artifact.created_at);
207 yield* ensure(
203 - Date.parse(step.startedAt) <= created && created <= Date.parse(step.completedAt),
208 + Date.parse(step.startedAt) - TIMESTAMP_SLACK_MS <= created &&
209 + created <= Date.parse(step.completedAt) + TIMESTAMP_SLACK_MS,
210 `${artifact.name} was created at ${artifact.created_at}, outside its upload step, which ran from ${step.startedAt} to ${step.completedAt}; add changesets and request a new release`
211 );
212 });
@@ -215,7 +221,7 @@ export const adoptApprovedCandidate = (sha: string, language: Language, director
221 const { workflow_runs } = yield* request(
222 'GET',
223 `${REPOSITORY_PATH}/actions/workflows/${CANDIDATES_WORKFLOW}/runs?event=pull_request&head_sha=${sha}&status=success&per_page=100`,
218 - Schema.Struct({ workflow_runs: Schema.Array(ReleaseRun) })
224 + WorkflowRuns
225 );
226 const [run] = workflow_runs
227 .filter(
scripts/sdk-release/channel.ts
+6 -3
@@ -20,8 +20,11 @@ export const CHANNELS = {
20 * commits only its plan, so `next` stays stable and every changeset stays pending.
21 */
22 commitsVersions: true,
23 - /** Checks the release PR head needs besides the candidate checks. */
24 - extraChecks: ['typescript-check'],
23 + /**
24 + * Checks the release PR head needs besides the candidate checks. The docs are checked against
25 + * the candidate packages, not the published ones the pull-request docs workflows install.
26 + */
27 + extraChecks: ['SDK candidate docs'],
28 /** Whether publishing opens a docs PR that pins the released npm versions. */
29 pinsDocs: true,
30 },
@@ -29,7 +32,7 @@ export const CHANNELS = {
32 // `beta` belongs to the 1.0 prerelease train on `main`; previews of `next` use `next`.
33 npmTag: 'next',
34 commitsVersions: false,
32 - // A beta PR does not touch the docs, so the docs check never runs on it.
35 + // A beta PR does not touch the docs, so no docs check runs on it.
36 extraChecks: [],
37 pinsDocs: false,
38 },
scripts/sdk-release/consumers.ts
+9 -2
@@ -313,13 +313,20 @@ const CONSUMERS: Record<Language, typeof verifyNpmConsumer | typeof verifyPython
313 python: verifyPythonConsumer,
314 };
315
316 +export const readVerifiedCandidate = (candidates: string) =>
317 + Effect.gen(function* () {
318 + const manifest = yield* readJson(CandidateManifest, `${candidates}/${CANDIDATE_MANIFEST}`);
319 + const files = yield* readCandidateFiles(candidates);
320 + yield* verifyCandidateFiles(files, manifest.files);
321 + return { manifest, files };
322 + });
323 +
324 /** Checks a downloaded candidate against its manifest, then installs and imports it like a user. */
325 export const verifyCandidateConsumers = (cwd: string, batch: ReleaseBatch, candidates: string) =>
326 Effect.scoped(
327 Effect.gen(function* () {
328 const fs = yield* FileSystem.FileSystem;
321 - const manifest = yield* readJson(CandidateManifest, `${candidates}/${CANDIDATE_MANIFEST}`);
322 - yield* verifyCandidateFiles(yield* readCandidateFiles(candidates), manifest.files);
329 + const { manifest } = yield* readVerifiedCandidate(candidates);
330 const directory = yield* fs.makeTempDirectoryScoped({ prefix: 'sdk-candidate-consumer-' });
331 yield* CONSUMERS[manifest.language](cwd, batch, directory, candidates);
332 const python = batch.plan.releases.find(release => release.language === 'python');
scripts/sdk-release/github.ts
+210 -38
@@ -1,5 +1,5 @@
1 -import { Context, Data, Effect, Layer, Option, Schema, Stream } from 'effect';
2 -import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/http';
1 +import { Context, Data, Duration, Effect, Layer, Option, Schema, Stream } from 'effect';
2 +import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from 'effect/http';
3 import { ensure } from './runtime';
4
5 export const SDK_RELEASE_REPOSITORY = 'ComposioHQ/composio';
@@ -7,6 +7,8 @@ export const REPOSITORY_PATH = `/repos/${SDK_RELEASE_REPOSITORY}`;
7 export const runUrl = (id: string | number) =>
8 `https://github.com/${SDK_RELEASE_REPOSITORY}/actions/runs/${id}`;
9 const PAGE_SIZE = 100;
10 +/** The REST API version every release request pins. */
11 +const GITHUB_API_VERSION = '2026-03-10';
12 /** Bounded so large release diffs stay under GitHub's secondary rate limit. */
13 export const CONTENT_CONCURRENCY = 8;
14
@@ -48,8 +50,11 @@ const ReleaseJob = Schema.Struct({
50 ).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
51 });
52
53 +const JobsPage = Schema.Struct({ jobs: Schema.Array(ReleaseJob) });
54 +
55 export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
56
57 +/** GitHub refused or failed a request; `message` carries GitHub's own reason and request ID. */
58 export class GitHubApiError extends Data.TaggedError('GitHubApiError')<{
59 readonly status: number;
60 readonly method: HttpMethod;
@@ -57,41 +62,213 @@ export class GitHubApiError extends Data.TaggedError('GitHubApiError')<{
62 readonly message: string;
63 }> {}
64
60 -const decodeBody = <S extends Schema.Top>(schema: S, text: string) =>
61 - text === ''
65 +/**
66 + * GitHub answered, but not in the shape the release workflow reads. Retrying cannot help: the
67 + * schemas need updating for the API version GitHub now serves.
68 + */
69 +export class GitHubContractError extends Data.TaggedError('GitHubContractError')<{
70 + readonly method: HttpMethod;
71 + readonly path: string;
72 + readonly message: string;
73 +}> {}
74 +
75 +const decodeBody = <S extends Schema.Top>(
76 + schema: S,
77 + text: string,
78 + method: HttpMethod,
79 + path: string
80 +) =>
81 + (text === ''
82 ? Schema.decodeUnknownEffect(schema)(undefined)
63 - : Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(text);
83 + : Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(text)
84 + ).pipe(
85 + Effect.mapError(
86 + error =>
87 + new GitHubContractError({
88 + method,
89 + path,
90 + message: `GitHub ${method} ${path} returned a response the release workflow cannot read under API version ${GITHUB_API_VERSION}: ${error.message}`,
91 + })
92 + )
93 + );
94 +
95 +/** How long one request may take, and how often and how long a failed one is retried. */
96 +export interface RetryPolicy {
97 + /** Attempts per request, the first one included. */
98 + readonly attempts: number;
99 + /** The first backoff; each later one doubles it. */
100 + readonly baseDelayMs: number;
101 + /** The longest single wait, including one GitHub asks for; a longer request gives up instead. */
102 + readonly maxDelayMs: number;
103 + /** Per-attempt timeout. */
104 + readonly timeout: Duration.Input;
105 +}
106 +
107 +const DEFAULT_RETRY: RetryPolicy = {
108 + attempts: 5,
109 + baseDelayMs: 1_000,
110 + maxDelayMs: 60_000,
111 + timeout: '30 seconds',
112 +};
113 +
114 +const ErrorBody = Schema.Struct({
115 + message: Schema.optionalKey(Schema.String),
116 + errors: Schema.optionalKey(
117 + Schema.Array(
118 + Schema.Struct({
119 + message: Schema.optionalKey(Schema.String),
120 + code: Schema.optionalKey(Schema.String),
121 + })
122 + )
123 + ),
124 +});
125 +
126 +/** GitHub's own explanation from an error body, such as "Validation Failed (already_exists)". */
127 +const githubReason = (text: string) => {
128 + const parsed = Schema.decodeUnknownOption(Schema.fromJsonString(ErrorBody))(text);
129 + if (Option.isNone(parsed)) return text.trim().slice(0, 300);
130 + const details = (parsed.value.errors ?? []).flatMap(error => error.message ?? error.code ?? []);
131 + return [parsed.value.message, details.length ? `(${details.join('; ')})` : '']
132 + .filter(Boolean)
133 + .join(' ');
134 +};
135 +
136 +const failure = (
137 + method: HttpMethod,
138 + path: string,
139 + response: HttpClientResponse.HttpClientResponse,
140 + text: string
141 +) => {
142 + const reason = githubReason(text);
143 + return new GitHubApiError({
144 + status: response.status,
145 + method,
146 + path,
147 + message: `GitHub ${method} ${path} failed (${response.status})${reason ? `: ${reason}` : ''} [request ${response.headers['x-github-request-id'] ?? 'unknown'}, API ${GITHUB_API_VERSION}]`,
148 + });
149 +};
150
65 -const makeGitHub = (token: string) =>
151 +/**
152 + * A rate limit, which GitHub did not process. Secondary limits answer 403 or 429 with
153 + * `retry-after`, an exhausted primary limit `x-ratelimit-remaining: 0`.
154 + */
155 +const isRateLimited = (response: HttpClientResponse.HttpClientResponse, text: string) =>
156 + response.status === 429 ||
157 + (response.status === 403 &&
158 + (response.headers['retry-after'] !== undefined ||
159 + response.headers['x-ratelimit-remaining'] === '0' ||
160 + /rate limit/i.test(text)));
161 +
162 +/** The wait GitHub asked for, from `retry-after` or the primary limit's reset time. */
163 +const requestedDelayMs = (response: HttpClientResponse.HttpClientResponse, now: number) => {
164 + const retryAfter = Number(response.headers['retry-after']);
165 + if (Number.isFinite(retryAfter) && retryAfter >= 0) return retryAfter * 1_000;
166 + const reset = Number(response.headers['x-ratelimit-reset']);
167 + if (response.headers['x-ratelimit-remaining'] === '0' && Number.isFinite(reset))
168 + return Math.max(0, reset * 1_000 - now);
169 + return undefined;
170 +};
171 +
172 +/** A response and its whole body, read within the same attempt timeout. */
173 +interface Answer {
174 + readonly response: HttpClientResponse.HttpClientResponse;
175 + readonly text: string;
176 +}
177 +
178 +type Attempt =
179 + | ({ readonly _tag: 'Done' } & Answer)
180 + | { readonly _tag: 'Retry'; readonly error: GitHubApiError; readonly delayMs?: number };
181 +
182 +const makeGitHub = (token: string, policy: RetryPolicy) =>
183 Effect.gen(function* () {
184 const client = yield* HttpClient.HttpClient;
68 - const send = (
185 + const sendOnce = (
186 method: HttpMethod,
187 path: string,
188 body: unknown,
189 redirect: RequestRedirect,
73 - accept = 'application/vnd.github+json'
190 + accept: string
191 ) =>
192 Effect.gen(function* () {
76 - yield* ensure(path.startsWith('/') && !path.startsWith('//'), 'Expected a GitHub API path');
193 const base = HttpClientRequest.make(method)(`https://api.github.com${path}`, {
194 headers: {
195 accept,
196 authorization: `Bearer ${token}`,
81 - 'x-github-api-version': '2026-03-10',
197 + 'x-github-api-version': GITHUB_API_VERSION,
198 },
199 });
84 - return yield* client.execute(
200 + const response = yield* client.execute(
201 body === undefined ? base : HttpClientRequest.bodyJsonUnsafe(base, body)
202 );
87 - }).pipe(Effect.provideService(FetchHttpClient.RequestInit, { redirect }));
88 - const failure = (method: HttpMethod, path: string, status: number) =>
89 - new GitHubApiError({
90 - status,
91 - method,
92 - path,
93 - message: `GitHub ${method} ${path} failed (${status})`,
203 + // The body is read here, so a response that stalls after its headers also times out.
204 + return { response, text: yield* response.text } satisfies Answer;
205 + }).pipe(
206 + Effect.provideService(FetchHttpClient.RequestInit, { redirect }),
207 + Effect.timeout(policy.timeout)
208 + );
209 + /**
210 + * One attempt, classified. Rate limits are retried for every method. Server errors and
211 + * timeouts are retried only for GET: GitHub sometimes applies a write before answering 502,
212 + * and repeating it would duplicate an issue or comment, or fail on a ref that now exists.
213 + */
214 + const attempt = (
215 + method: HttpMethod,
216 + path: string,
217 + body: unknown,
218 + redirect: RequestRedirect,
219 + accept: string
220 + ) =>
221 + sendOnce(method, path, body, redirect, accept).pipe(
222 + Effect.matchEffect({
223 + onFailure: (cause): Effect.Effect<Attempt, GitHubApiError> => {
224 + const error = new GitHubApiError({
225 + status: 0,
226 + method,
227 + path,
228 + message: `GitHub ${method} ${path} did not answer: ${cause.message}`,
229 + });
230 + return method === 'GET' ? Effect.succeed({ _tag: 'Retry', error }) : Effect.fail(error);
231 + },
232 + onSuccess: ({ response, text }) =>
233 + Effect.gen(function* () {
234 + const retryable =
235 + response.status === 429 ||
236 + response.status === 403 ||
237 + (response.status >= 500 && method === 'GET');
238 + if (!retryable) return { _tag: 'Done', response, text } satisfies Attempt;
239 + if (response.status === 403 && !isRateLimited(response, text))
240 + return yield* failure(method, path, response, text);
241 + return {
242 + _tag: 'Retry',
243 + error: failure(method, path, response, text),
244 + delayMs: requestedDelayMs(response, Date.now()),
245 + } satisfies Attempt;
246 + }),
247 + })
248 + );
249 + const send = (
250 + method: HttpMethod,
251 + path: string,
252 + body: unknown,
253 + redirect: RequestRedirect,
254 + accept = 'application/vnd.github+json'
255 + ) =>
256 + Effect.gen(function* () {
257 + yield* ensure(path.startsWith('/') && !path.startsWith('//'), 'Expected a GitHub API path');
258 + for (let tries = 1; ; tries++) {
259 + const outcome = yield* attempt(method, path, body, redirect, accept);
260 + if (outcome._tag === 'Done') return { response: outcome.response, text: outcome.text };
261 + const delayMs = outcome.delayMs ?? policy.baseDelayMs * 2 ** (tries - 1);
262 + if (tries >= policy.attempts || delayMs > policy.maxDelayMs)
263 + return yield* new GitHubApiError({
264 + ...outcome.error,
265 + message: `${outcome.error.message}; gave up after ${tries} attempt${tries === 1 ? '' : 's'}`,
266 + });
267 + yield* Effect.sleep(delayMs);
268 + }
269 });
270 + const failResponse = (method: HttpMethod, path: string, { response, text }: Answer) =>
271 + Effect.fail(failure(method, path, response, text));
272 return {
273 request: <S extends Schema.Top>(
274 method: HttpMethod,
@@ -100,32 +277,26 @@ const makeGitHub = (token: string) =>
277 body?: unknown
278 ) =>
279 Effect.gen(function* () {
103 - const response = yield* send(method, path, body, 'error');
104 - if (response.status < 200 || response.status >= 300)
105 - return yield* failure(method, path, response.status);
106 - return yield* decodeBody(schema, yield* response.text);
280 + const answer = yield* send(method, path, body, 'error');
281 + if (answer.response.status < 200 || answer.response.status >= 300)
282 + return yield* failResponse(method, path, answer);
283 + return yield* decodeBody(schema, answer.text, method, path);
284 }),
285 /** A file's raw contents, or `None` on 404. Raw media works for files over 1 MB. */
286 raw: (path: string) =>
287 Effect.gen(function* () {
111 - const response = yield* send(
112 - 'GET',
113 - path,
114 - undefined,
115 - 'error',
116 - 'application/vnd.github.raw'
117 - );
118 - if (response.status === 404) return Option.none<string>();
119 - if (response.status < 200 || response.status >= 300)
120 - return yield* failure('GET', path, response.status);
121 - return Option.some(yield* response.text);
288 + const answer = yield* send('GET', path, undefined, 'error', 'application/vnd.github.raw');
289 + if (answer.response.status === 404) return Option.none<string>();
290 + if (answer.response.status < 200 || answer.response.status >= 300)
291 + return yield* failResponse('GET', path, answer);
292 + return Option.some(answer.text);
293 }),
294 /** Resolves an endpoint that answers with a 302 to short-lived storage, such as an artifact archive. */
295 redirectLocation: (path: string) =>
296 Effect.gen(function* () {
126 - const response = yield* send('GET', path, undefined, 'manual');
127 - if (response.status !== 302) return yield* failure('GET', path, response.status);
128 - return Option.fromNullishOr(response.headers.location);
297 + const answer = yield* send('GET', path, undefined, 'manual');
298 + if (answer.response.status !== 302) return yield* failResponse('GET', path, answer);
299 + return Option.fromNullishOr(answer.response.headers.location);
300 }),
301 };
302 });
@@ -135,7 +306,8 @@ export class GitHub extends Context.Service<
306 GitHub,
307 Effect.Success<ReturnType<typeof makeGitHub>>
308 >()('sdk-release/GitHub') {
138 - static readonly layer = (token: string) => Layer.effect(GitHub, makeGitHub(token));
309 + static readonly layer = (token: string, retry: Partial<RetryPolicy> = {}) =>
310 + Layer.effect(GitHub, makeGitHub(token, { ...DEFAULT_RETRY, ...retry }));
311 }
312
313 export const request = <S extends Schema.Top>(
@@ -213,7 +385,7 @@ export const jobs = (id: string, filter: 'all' | 'latest' = 'all') =>
385 Stream.runCollect(
386 paginate(
387 `${REPOSITORY_PATH}/actions/runs/${id}/jobs?filter=${filter}`,
216 - Schema.Struct({ jobs: Schema.Array(ReleaseJob) }),
388 + JobsPage,
389 body => body.jobs
390 )
391 );
scripts/sdk-release/npm-oidc.ts new
+133
@@ -0,0 +1,133 @@
1 +import { Config, Console, Effect, Option, Redacted, Schema } from 'effect';
2 +import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/http';
3 +import { NPM_REGISTRY } from './lanes';
4 +import { RELEASE_PUBLISHER } from './provenance';
5 +import { isSuccess } from './registry-wait';
6 +import { fail } from './runtime';
7 +
8 +/** The runbook section on npm trusted publishers, linked from every npm login failure. */
9 +export const NPM_TRUSTED_PUBLISHING_RUNBOOK = 'ts/docs/internal/release.md#npm-trusted-publishing';
10 +
11 +/** Where an owner changes a package's trusted publisher; the npm CLI cannot change it. */
12 +export const npmTrustedPublisherSettings = (name: string) =>
13 + `npmjs.com → ${name} → Settings → Trusted publishing`;
14 +
15 +const REQUEST_TIMEOUT = '30 seconds';
16 +
17 +/** The audience npm requests the GitHub ID token for, as npm CLI 11.21.0 does. */
18 +const AUDIENCE = `npm:${new URL(NPM_REGISTRY).hostname}`;
19 +
20 +/** npm's per-package exchange endpoint; npm escapes only the scope's slash, as `%2f`. */
21 +const exchangeUrl = (name: string) =>
22 + `${NPM_REGISTRY}/-/npm/v1/oidc/token/exchange/package/${name.replaceAll('/', '%2f')}`;
23 +
24 +const present = <A>(value: Option.Option<A>, text: (value: A) => string) =>
25 + Option.filter(value, item => text(item) !== '');
26 +
27 +const IdTokenRequest = Config.all({
28 + url: Config.option(Config.String('ACTIONS_ID_TOKEN_REQUEST_URL')),
29 + token: Config.option(Config.Redacted('ACTIONS_ID_TOKEN_REQUEST_TOKEN')),
30 +});
31 +
32 +const IdToken = Schema.fromJsonString(Schema.Struct({ value: Schema.NonEmptyString }));
33 +const ExchangedToken = Schema.fromJsonString(Schema.Struct({ token: Schema.NonEmptyString }));
34 +const NpmErrorBody = Schema.fromJsonString(Schema.Struct({ message: Schema.String }));
35 +
36 +/**
37 + * Sends one request and returns its status and body. Transport failures become a fixed message,
38 + * so a request's credentials can never surface in an error.
39 + */
40 +const send = (request: HttpClientRequest.HttpClientRequest, failure: string) =>
41 + Effect.gen(function* () {
42 + const client = yield* HttpClient.HttpClient;
43 + const response = yield* client.execute(request);
44 + return { status: response.status, text: yield* response.text };
45 + }).pipe(
46 + Effect.provideService(FetchHttpClient.RequestInit, { redirect: 'error' }),
47 + Effect.timeout(REQUEST_TIMEOUT),
48 + Effect.catch(() => fail(failure))
49 + );
50 +
51 +/** Requests the GitHub ID token for npm, as npm does before trusted publishing. */
52 +const githubIdToken = Effect.gen(function* () {
53 + const env = yield* IdTokenRequest;
54 + const url = present(env.url, value => value);
55 + const token = present(env.token, Redacted.value);
56 + if (Option.isNone(url) || Option.isNone(token))
57 + return yield* fail(
58 + 'GitHub id-token permission missing: ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN are unset, so npm trusted publishing cannot log in. The publish-npm job needs `permissions: id-token: write`.'
59 + );
60 + const target = new URL(url.value);
61 + target.searchParams.append('audience', AUDIENCE);
62 + const response = yield* send(
63 + HttpClientRequest.get(target.href, {
64 + headers: {
65 + accept: 'application/json',
66 + authorization: `Bearer ${Redacted.value(token.value)}`,
67 + },
68 + }),
69 + 'The GitHub OIDC ID token request did not answer'
70 + );
71 + const body = Schema.decodeUnknownOption(IdToken)(response.text);
72 + if (!isSuccess(response.status) || Option.isNone(body))
73 + return yield* fail(`GitHub did not issue an OIDC ID token for npm (${response.status})`);
74 + return Redacted.make(body.value.value);
75 +});
76 +
77 +/** npm's reason for refusing an exchange: its `message`, else the body as it came. */
78 +const npmReason = (text: string) =>
79 + Option.match(Schema.decodeUnknownOption(NpmErrorBody)(text), {
80 + onNone: () => text.trim() || 'empty response',
81 + onSome: body => body.message,
82 + });
83 +
84 +/** One package's exchange; the exchanged token is checked for presence and then dropped. */
85 +const exchange = (name: string, idToken: Redacted.Redacted<string>) =>
86 + Effect.gen(function* () {
87 + const response = yield* send(
88 + HttpClientRequest.post(exchangeUrl(name), {
89 + headers: { accept: 'application/json', authorization: `Bearer ${Redacted.value(idToken)}` },
90 + }),
91 + `The npm trusted-publishing exchange for ${name} did not answer`
92 + );
93 + if (
94 + isSuccess(response.status) &&
95 + Option.isSome(Schema.decodeUnknownOption(ExchangedToken)(response.text))
96 + )
97 + return Option.none<string>();
98 + return Option.some(
99 + isSuccess(response.status)
100 + ? `${name} (${response.status}): npm answered without a token`
101 + : `${name} (${response.status}): ${npmReason(response.text)}`
102 + );
103 + });
104 +
105 +/**
106 + * Logs in to npm through trusted publishing for every package, the way `npm publish` and
107 + * `npm dist-tag` will, and prints npm's answer for each. Fails before anything is uploaded when
108 + * npm refuses any of them, naming each package and npm's reason. Every planned package is
109 + * checked, not only the ones still missing, because moving a dist-tag needs the same login.
110 + */
111 +export const checkNpmLogin = (names: ReadonlyArray<string>) =>
112 + Effect.gen(function* () {
113 + const idToken = yield* githubIdToken;
114 + const refusals: string[] = [];
115 + for (const name of names) {
116 + const refusal = yield* exchange(name, idToken);
117 + yield* Console.log(
118 + Option.match(refusal, {
119 + onNone: () => `npm trusted publishing accepted ${name}`,
120 + onSome: reason => `npm trusted publishing refused ${reason}`,
121 + })
122 + );
123 + if (Option.isSome(refusal)) refusals.push(refusal.value);
124 + }
125 + if (refusals.length > 0)
126 + return yield* fail(
127 + [
128 + `npm refused the trusted-publishing login for ${refusals.length} of ${names.length} packages, so nothing was uploaded:`,
129 + ...refusals.map(reason => ` ${reason}`),
130 + `Check each package's trusted publisher (${npmTrustedPublisherSettings('<package>')}): repository ${RELEASE_PUBLISHER.repository}, workflow ${RELEASE_PUBLISHER.workflow}, environment npm-release. See ${NPM_TRUSTED_PUBLISHING_RUNBOOK}.`,
131 + ].join('\n')
132 + );
133 + });
scripts/sdk-release/provenance.ts
+44 -29
@@ -1,11 +1,11 @@
1 -import { Data, Effect, Schedule, Schema } from 'effect';
2 -import type { Duration } from 'effect';
1 +import { Data, Effect, Schema } from 'effect';
2 import { Digest } from 'effect/crypto';
3 import { Base64 } from 'effect/encoding';
4 import { FetchHttpClient, HttpClient } from 'effect/http';
5 import { SDK_RELEASE_REPOSITORY } from './github';
6 import { NPM_REGISTRY } from './lanes';
7 import type { Distribution } from './registry';
8 +import { REGISTRY_WAIT, isPending, pollRegistry, type RegistryDeadline } from './registry-wait';
9 import { ensure, fail } from './runtime';
10 import { releaseTag } from './source';
11
@@ -53,31 +53,46 @@ const PypiProvenance = Schema.Struct({
53 ),
54 });
55
56 -/** Provenance can trail an upload by a few seconds, so a missing document is retried. */
57 -class ProvenancePending extends Data.TaggedError('ProvenancePending')<{ readonly url: string }> {}
58 -
59 -/** How long to wait for provenance that trails an upload. */
60 -export interface ProvenanceWait {
61 - readonly attempts?: number;
62 - readonly spacing?: Duration.Input;
63 -}
56 +/**
57 + * Provenance trails an upload by up to npm's publish-time scan, so a missing document is polled
58 + * again; so is a rate limit or a server error.
59 + */
60 +class ProvenancePending extends Data.TaggedError('ProvenancePending')<{
61 + readonly url: string;
62 + readonly status: number | 'timeout';
63 +}> {}
64
65 -const provenanceJson = <S extends Schema.Top>(url: string, schema: S, wait: ProvenanceWait) =>
66 - Effect.gen(function* () {
67 - const client = yield* HttpClient.HttpClient;
68 - const response = yield* client.get(url);
69 - if (response.status === 404) return yield* new ProvenancePending({ url });
70 - yield* ensure(response.status === 200, `Provenance lookup failed: ${url} (${response.status})`);
71 - return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(yield* response.text);
72 - }).pipe(
73 - Effect.provideService(FetchHttpClient.RequestInit, { redirect: 'error' }),
74 - Effect.retry({
75 - schedule: Schedule.spaced(wait.spacing ?? '10 seconds'),
76 - times: (wait.attempts ?? 6) - 1,
77 - while: error => error instanceof ProvenancePending,
78 - }),
65 +const provenanceJson = <S extends Schema.Top>(
66 + url: string,
67 + schema: S,
68 + deadline?: RegistryDeadline
69 +) =>
70 + pollRegistry(
71 + Effect.gen(function* () {
72 + const client = yield* HttpClient.HttpClient;
73 + const response = yield* client.get(url);
74 + if (isPending(response.status))
75 + return yield* new ProvenancePending({ url, status: response.status });
76 + yield* ensure(
77 + response.status === 200,
78 + `Provenance lookup failed: ${url} (${response.status})`
79 + );
80 + return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(yield* response.text);
81 + }).pipe(
82 + Effect.provideService(FetchHttpClient.RequestInit, { redirect: 'error' }),
83 + // A stalled lookup is retried like an answer that is not served yet.
84 + Effect.timeoutOrElse({
85 + duration: REGISTRY_WAIT.requestTimeout,
86 + orElse: () => Effect.fail(new ProvenancePending({ url, status: 'timeout' })),
87 + })
88 + ),
89 + error => error instanceof ProvenancePending,
90 + deadline
91 + ).pipe(
92 Effect.catchTag('ProvenancePending', error =>
80 - fail(`No provenance is published at ${error.url}`)
93 + fail(
94 + `No provenance is published at ${error.url} when the registry wait (${REGISTRY_WAIT.deadline}) ended; its last answer was ${error.status}`
95 + )
96 )
97 );
98
@@ -85,10 +100,10 @@ const provenanceJson = <S extends Schema.Top>(url: string, schema: S, wait: Prov
100 * The npm SLSA provenance of a published tarball must name this repository, the release
101 * workflow and this batch's tag, and its subject must be the reviewed bytes.
102 */
88 -export const verifyNpmProvenance = (file: Distribution, id: string, wait: ProvenanceWait = {}) =>
103 +export const verifyNpmProvenance = (file: Distribution, id: string, deadline?: RegistryDeadline) =>
104 Effect.gen(function* () {
105 const url = `${NPM_REGISTRY}/-/npm/v1/attestations/${encodeURIComponent(file.name)}@${file.version}`;
91 - const { attestations } = yield* provenanceJson(url, NpmAttestations, wait);
106 + const { attestations } = yield* provenanceJson(url, NpmAttestations, deadline);
107 const slsa = attestations.find(attestation => attestation.predicateType === SLSA_PROVENANCE);
108 if (!slsa) return yield* fail(`${file.name}@${file.version} has no SLSA provenance`);
109 const payload = yield* Effect.fromResult(Base64.decodeString(slsa.bundle.dsseEnvelope.payload));
@@ -111,10 +126,10 @@ export const verifyNpmProvenance = (file: Distribution, id: string, wait: Proven
126 });
127
128 /** Every PyPI file must carry a PEP 740 attestation from this repository's release workflow. */
114 -export const verifyPypiProvenance = (file: Distribution, wait: ProvenanceWait = {}) =>
129 +export const verifyPypiProvenance = (file: Distribution, deadline?: RegistryDeadline) =>
130 Effect.gen(function* () {
131 const url = `https://pypi.org/integrity/${file.name}/${file.version}/${file.file}/provenance`;
117 - const { attestation_bundles } = yield* provenanceJson(url, PypiProvenance, wait);
132 + const { attestation_bundles } = yield* provenanceJson(url, PypiProvenance, deadline);
133 yield* ensure(
134 attestation_bundles.some(
135 ({ publisher }) =>
scripts/sdk-release/registry-wait.ts new
+49
@@ -0,0 +1,49 @@
1 +import { Clock, Duration, Effect, Schedule } from 'effect';
2 +
3 +/**
4 + * How long the release waits for npm and PyPI to serve an upload and its provenance, and how
5 + * often it looks. npm scans every new version before serving it, which takes about 5 to 15
6 + * minutes, so the deadline leaves room for a slow scan.
7 + */
8 +export const REGISTRY_WAIT = {
9 + deadline: '20 minutes',
10 + firstDelay: '5 seconds',
11 + maxDelay: '1 minute',
12 + requestTimeout: '30 seconds',
13 +} as const satisfies Record<string, Duration.Input>;
14 +
15 +export const isSuccess = (status: number) => status >= 200 && status < 300;
16 +
17 +/** Answers that waiting can fix: not served yet, rate limited, or a registry outage. */
18 +export const isPending = (status: number) => status === 404 || status === 429 || status >= 500;
19 +
20 +export type RegistryDeadline = number;
21 +
22 +export const registryDeadline: Effect.Effect<RegistryDeadline> = Effect.map(
23 + Clock.currentTimeMillis,
24 + now => now + Duration.toMillis(REGISTRY_WAIT.deadline)
25 +);
26 +
27 +const backoff = Schedule.exponential(REGISTRY_WAIT.firstDelay).pipe(
28 + Schedule.modifyDelay(({ duration }) =>
29 + Effect.succeed(Duration.min(duration, Duration.fromInputUnsafe(REGISTRY_WAIT.maxDelay)))
30 + ),
31 + Schedule.jittered
32 +);
33 +
34 +/**
35 + * Retries `effect` while its error is `pending`, backing off exponentially with jitter, until
36 + * `deadline` (the registry wait deadline from now, when omitted). Other errors fail at once.
37 + */
38 +export const pollRegistry = <A, E, R>(
39 + effect: Effect.Effect<A, E, R>,
40 + pending: (error: E) => boolean,
41 + deadline?: RegistryDeadline
42 +) =>
43 + Effect.gen(function* () {
44 + const until = deadline ?? (yield* registryDeadline);
45 + return yield* Effect.retry(effect, {
46 + schedule: backoff,
47 + while: error => pending(error) && Effect.map(Clock.currentTimeMillis, now => now < until),
48 + });
49 + });
scripts/sdk-release/registry.ts
+111 -47
@@ -1,18 +1,18 @@
1 import {
2 Config,
3 + Console,
4 Context,
5 Data,
6 + Duration,
7 Effect,
8 FileSystem,
9 Layer,
10 Option,
11 Path,
10 - Schedule,
12 Schema,
13 Stdio,
14 } from 'effect';
15 import { ChildProcessSpawner } from 'effect/process';
15 -import type { Duration } from 'effect';
16 import { FetchHttpClient, HttpClient } from 'effect/http';
17 import semver from 'semver';
18 import {
@@ -36,9 +36,19 @@ import {
36 Language,
37 type Language as Lang,
38 } from './lanes';
39 -import { verifyNpmProvenance, verifyPypiProvenance, type ProvenanceWait } from './provenance';
39 +import { verifyNpmProvenance, verifyPypiProvenance } from './provenance';
40 +import {
41 + REGISTRY_WAIT,
42 + isPending,
43 + isSuccess,
44 + pollRegistry,
45 + registryDeadline,
46 + type RegistryDeadline,
47 +} from './registry-wait';
48 import { discoverPythonPackages } from './python-metadata';
49 import {
50 + CommandError,
51 + ReleaseError,
52 appendFile,
53 ensure,
54 fail,
@@ -50,6 +60,11 @@ import {
60 withoutReleaseTokens,
61 } from './runtime';
62 import { BATCH_PATH, ReleaseBatch, batchLanguages, releaseTag } from './source';
63 +import {
64 + NPM_TRUSTED_PUBLISHING_RUNBOOK,
65 + checkNpmLogin,
66 + npmTrustedPublisherSettings,
67 +} from './npm-oidc';
68
69 /** One reviewed distribution file: an npm tarball or a Python wheel/sdist. */
70 export interface Distribution {
@@ -75,14 +90,10 @@ export interface RegistryState {
90 readonly tagsToRepair: ReadonlyArray<ChannelTag>;
91 }
92
78 -const REGISTRY_TIMEOUT = '30 seconds';
79 -
93 const Url = Schema.String.check(
94 Schema.makeFilter(value => (URL.canParse(value) ? undefined : 'Expected a URL'))
95 );
96
84 -const isSuccess = (status: number) => status >= 200 && status < 300;
85 -
97 const registryGet = (url: string) =>
98 Effect.gen(function* () {
99 const client = yield* HttpClient.HttpClient;
@@ -93,27 +104,33 @@ const registryGet = (url: string) =>
104 class RegistryIncomplete extends Data.TaggedError('RegistryIncomplete')<{
105 readonly message: string;
106 }> {}
96 -const incomplete = (condition: boolean, message: string) =>
97 - condition ? Effect.void : Effect.fail(new RegistryIncomplete({ message }));
107 +/** Fails at once on an answer waiting cannot fix, and as still pending on any other failure. */
108 +const served = (status: number, pending: string, failed = pending) =>
109 + isSuccess(status)
110 + ? Effect.void
111 + : isPending(status)
112 + ? Effect.fail(new RegistryIncomplete({ message: pending }))
113 + : fail(failed);
114
115 /** Registry metadata at `url`, or `None` when the registry answers 404. */
116 const registryJson = <S extends Schema.Top>(url: string, schema: S) =>
117 Effect.gen(function* () {
118 const response = yield* registryGet(url);
119 if (response.status === 404) return Option.none<S['Type']>();
104 - yield* incomplete(
105 - isSuccess(response.status),
106 - `Registry lookup incomplete: ${url} (${response.status})`
120 + yield* served(
121 + response.status,
122 + `Registry lookup incomplete: ${url} (${response.status})`,
123 + `Registry lookup failed: ${url} (${response.status})`
124 );
125 return Option.some(yield* parseJson(schema, yield* response.text));
109 - }).pipe(Effect.timeout(REGISTRY_TIMEOUT));
126 + }).pipe(Effect.timeout(REGISTRY_WAIT.requestTimeout));
127
128 const registryBytes = (url: string, failure: (status: number) => string) =>
129 Effect.gen(function* () {
130 const response = yield* registryGet(url);
114 - yield* incomplete(isSuccess(response.status), failure(response.status));
131 + yield* served(response.status, failure(response.status));
132 return new Uint8Array(yield* response.arrayBuffer);
116 - }).pipe(Effect.timeout(REGISTRY_TIMEOUT));
133 + }).pipe(Effect.timeout(REGISTRY_WAIT.requestTimeout));
134
135 const servedBy = (language: Lang, url: string) =>
136 URL.canParse(url) &&
@@ -330,39 +347,38 @@ const incompleteInventory = (state: RegistryState, channelTags: boolean) =>
347
348 /**
349 * Polls the registries until every file is visible, and every channel tag too unless
333 - * `channelTags` is false (right after an upload, before the channel tag moves).
350 + * `channelTags` is false (right after an upload, before the channel tag moves). npm serves a new
351 + * version only after its publish-time scan, so the wait runs until `deadline` (the registry wait
352 + * deadline from now, when omitted). Served bytes that differ from the candidate fail at once.
353 */
354 export const waitForRegistry = (
355 files: ReadonlyArray<Distribution>,
356 options: {
338 - readonly attempts?: number;
339 - readonly spacing?: Duration.Input;
357 readonly channelTags?: boolean;
358 readonly channel?: Channel;
359 + readonly deadline?: RegistryDeadline;
360 } = {}
343 -) => {
344 - const attempts = options.attempts ?? 6;
345 - return reconcileRegistry(files, options.channel).pipe(
346 - Effect.flatMap(state => {
347 - const missing = incompleteInventory(state, options.channelTags ?? true);
348 - return missing
349 - ? Effect.fail(new RegistryIncomplete({ message: missing }))
350 - : Effect.succeed(state);
351 - }),
352 - Effect.retry({
353 - schedule: Schedule.spaced(options.spacing ?? '10 seconds'),
354 - times: attempts - 1,
355 - while: error => error instanceof RegistryIncomplete,
356 - }),
361 +) =>
362 + pollRegistry(
363 + reconcileRegistry(files, options.channel).pipe(
364 + Effect.flatMap(state => {
365 + const missing = incompleteInventory(state, options.channelTags ?? true);
366 + return missing
367 + ? Effect.fail(new RegistryIncomplete({ message: missing }))
368 + : Effect.succeed(state);
369 + })
370 + ),
371 + error => error instanceof RegistryIncomplete,
372 + options.deadline
373 + ).pipe(
374 Effect.catchTag('RegistryIncomplete', error =>
375 Effect.fail(
376 new RegistryIncomplete({
360 - message: `Registry verification incomplete after ${attempts} attempts: ${error.message}`,
377 + message: `Registry verification incomplete when the registry wait (${REGISTRY_WAIT.deadline}) ended: ${error.message}`,
378 })
379 )
380 )
381 );
365 -};
382
383 /**
384 * Downloads the approved release-PR artifact pinned for `language` and checks its files
@@ -438,9 +454,40 @@ export class NpmCli extends Context.Service<
454 }
455
456 /**
441 - * Publishes under a release-only dist-tag, checks that each tarball's provenance names this
442 - * release, then moves the channel's tag and drops the release-only tag. A failed check leaves
443 - * the channel tag where it was.
457 + * Runs `npm dist-tag add|rm` for `name`. npm refuses a trusted publisher without the dist-tag
458 + * permission with a bare E403, so that refusal is reported with the setting that fixes it.
459 + */
460 +export const npmDistTag = (args: readonly ['add' | 'rm', string, string], name: string) =>
461 + Effect.gen(function* () {
462 + const cli = yield* NpmCli;
463 + return yield* cli.run(['dist-tag', ...args]);
464 + }).pipe(
465 + Effect.mapError(error =>
466 + error instanceof CommandError && error.message.includes('cannot manage dist-tags')
467 + ? new ReleaseError({
468 + message: `npm refused \`npm dist-tag ${args.join(' ')}\`: the trusted publisher of ${name} lacks the "Allow npm dist-tag" permission. A package maintainer must enable it at ${npmTrustedPublisherSettings(name)}; the npm CLI cannot. Then re-run this job. See ${NPM_TRUSTED_PUBLISHING_RUNBOOK}.\n${error.message}`,
469 + })
470 + : error
471 + )
472 + );
473 +
474 +/**
475 + * How npm 11.21.0 refuses to upload a version the registry already holds. npm holds a version
476 + * from its upload on, before its publish-time scan ends and the registry serves it, so a re-run
477 + * during the scan meets this refusal.
478 + */
479 +const alreadyUploaded = (error: unknown, file: Distribution) =>
480 + error instanceof CommandError &&
481 + error.message.includes(
482 + `You cannot publish over the previously published versions: ${file.version}.`
483 + );
484 +
485 +/**
486 + * Checks the npm trusted-publishing login for every package, publishes under a release-only
487 + * dist-tag, checks that each tarball's provenance names this release, then moves the channel's
488 + * tag and drops the release-only tag. A failed check leaves the channel tag where it was. A
489 + * version npm already holds is not uploaded again: the wait for the registry then compares the
490 + * bytes npm serves with the reviewed tarball.
491 */
492 export const publishNpm = (cwd: string, batch: ReleaseBatch, files: ReadonlyArray<Distribution>) =>
493 Effect.gen(function* () {
@@ -448,6 +495,7 @@ export const publishNpm = (cwd: string, batch: ReleaseBatch, files: ReadonlyArra
495 const channel = batch.plan.choices.channel;
496 const cli = yield* NpmCli;
497 const npm = cli.run;
498 + yield* checkNpmLogin(files.map(file => file.name));
499 for (const file of (yield* reconcileRegistry(files, channel)).missing)
500 yield* npm([
501 'publish',
@@ -456,12 +504,22 @@ export const publishNpm = (cwd: string, batch: ReleaseBatch, files: ReadonlyArra
504 '--provenance',
505 '--access=public',
506 `--tag=sdk-release-${batch.id}`,
459 - ]);
460 - const visible = yield* waitForRegistry(files, { channelTags: false, channel });
507 + ]).pipe(
508 + Effect.catchIf(
509 + error => alreadyUploaded(error, file),
510 + () =>
511 + Console.log(
512 + `npm already holds ${file.name}@${file.version} but does not serve it yet, as during its publish-time scan; waiting for it instead of uploading again.`
513 + )
514 + )
515 + );
516 + // Visibility and provenance share one deadline, which npm's publish-time scan fits in.
517 + const deadline = yield* registryDeadline;
518 + const visible = yield* waitForRegistry(files, { channelTags: false, channel, deadline });
519 // Users only install a version once its channel tag moves, so it moves after the checks.
462 - for (const file of files) yield* verifyNpmProvenance(file, batch.id);
520 + for (const file of files) yield* verifyNpmProvenance(file, batch.id, deadline);
521 for (const tag of visible.tagsToRepair)
464 - yield* npm(['dist-tag', 'add', `${tag.name}@${tag.version}`, tag.tag]);
522 + yield* npmDistTag(['add', `${tag.name}@${tag.version}`, tag.tag], tag.name);
523 yield* waitForRegistry(files, { channel });
524 // The release-only tag only served the upload; a re-run finds it already gone.
525 const releaseOnly = `sdk-release-${batch.id}`;
@@ -471,7 +529,7 @@ export const publishNpm = (cwd: string, batch: ReleaseBatch, files: ReadonlyArra
529 Schema.Record(Schema.String, Schema.String)
530 );
531 if (Option.exists(tags, value => releaseOnly in value))
474 - yield* npm(['dist-tag', 'rm', file.name, releaseOnly]);
532 + yield* npmDistTag(['rm', file.name, releaseOnly], file.name);
533 }
534 });
535
@@ -483,11 +541,11 @@ export const npmSpecs = (files: ReadonlyArray<Distribution>) =>
541 * Checks that every PyPI file is attested by this release, and returns the file URLs for the
542 * signature check that `pypi-attestations` runs next.
543 */
486 -export const verifyPypiFiles = (files: ReadonlyArray<Distribution>, wait: ProvenanceWait = {}) =>
544 +export const verifyPypiFiles = (files: ReadonlyArray<Distribution>, deadline?: RegistryDeadline) =>
545 Effect.gen(function* () {
546 const urls: string[] = [];
547 for (const file of files) {
490 - yield* verifyPypiProvenance(file, wait);
548 + yield* verifyPypiProvenance(file, deadline);
549 const metadata = yield* registryJson(
550 REGISTRY_LANES.python.versionUrl(file.name, file.version),
551 PypiVersion
@@ -550,12 +608,18 @@ const main = Effect.gen(function* () {
608 );
609 yield* Effect.gen(function* () {
610 if (mode === 'verify') {
553 - yield* waitForRegistry(files, { channel: batch.plan.choices.channel });
554 - return yield* appendFile(env.output, `files=${(yield* verifyPypiFiles(files)).join(' ')}\n`);
611 + const deadline = yield* registryDeadline;
612 + yield* waitForRegistry(files, { channel: batch.plan.choices.channel, deadline });
613 + const urls = yield* verifyPypiFiles(files, deadline);
614 + return yield* appendFile(env.output, `files=${urls.join(' ')}\n`);
615 }
616 if (language === 'typescript') {
617 yield* publishNpm(cwd, batch, files);
558 - return yield* appendFile(env.output, `specs=${npmSpecs(files)}\n`);
618 + // The fresh-install step retries for as long as the registry wait.
619 + return yield* appendFile(
620 + env.output,
621 + `specs=${npmSpecs(files)}\nwait_seconds=${Duration.toSeconds(REGISTRY_WAIT.deadline)}\n`
622 + );
623 }
624 yield* stageMissingPython(cwd, files, env.output);
625 }).pipe(Effect.provide(NpmCli.layer(cwd)));
scripts/sdk-release/release-pr.ts
+11 -4
@@ -8,11 +8,11 @@ const RELEASE_BRANCH = /^sdk-release\/batch-\d+$/;
8
9 export const releaseBranch = (id: string) => `sdk-release/batch-${id}`;
10
11 -export const Pull = Schema.Struct({
11 +/** A pull request as list endpoints return it. They never say whether it merged. */
12 +export const PullListItem = Schema.Struct({
13 number: PositiveInt,
14 html_url: Schema.String,
15 state: Schema.String,
15 - merged: Schema.optionalKey(Schema.Boolean),
16 /** `null` when the author's account was deleted. */
17 user: Schema.NullOr(Schema.Struct({ login: Schema.String })),
18 head: Schema.Struct({
@@ -22,9 +22,16 @@ export const Pull = Schema.Struct({
22 }),
23 base: Schema.Struct({ ref: Schema.String }),
24 });
25 -export type Pull = typeof Pull.Type;
25 +export type PullListItem = typeof PullListItem.Type;
26
27 -export const isReleasePull = (pull: Pull) =>
27 +/**
28 + * A single pull request. The gate decides on `merged`, so a response without it is a contract
29 + * failure rather than an unmerged PR.
30 + */
31 +export const PullDetail = Schema.Struct({ ...PullListItem.fields, merged: Schema.Boolean });
32 +export type PullDetail = typeof PullDetail.Type;
33 +
34 +export const isReleasePull = (pull: PullListItem) =>
35 pull.head.repo?.full_name === SDK_RELEASE_REPOSITORY && RELEASE_BRANCH.test(pull.head.ref);
36
37 const NOTE_EXEMPT =
scripts/sdk-release/report.ts
+4
@@ -28,6 +28,7 @@ const IssueComment = Schema.Struct({
28 user: Schema.NullOr(Schema.Struct({ login: Schema.String })),
29 });
30 const IssueLabel = Schema.Struct({ name: Schema.String });
31 +const IssueState = Schema.Struct({ state: Schema.Literals(['open', 'closed']) });
32 const Written = Schema.Unknown;
33
34 /**
@@ -70,6 +71,9 @@ export const showStatus = (issue: number, state: ReleaseState, run: string, stag
71 yield* request('POST', `${issuePath}/labels`, Written, { labels: [display.label] });
72 if (display.close)
73 yield* request('PATCH', issuePath, Written, { state: 'closed', state_reason: display.close });
74 + // A release that can advance again, such as one re-gated after a refusal, reopens its issue.
75 + else if ((yield* request('GET', issuePath, IssueState)).state === 'closed')
76 + yield* request('PATCH', issuePath, Written, { state: 'open' });
77 });
78
79 /** A job's result as GitHub reports it to the jobs that need it. */
scripts/sdk-release/state.ts
+6 -3
@@ -81,10 +81,13 @@ export const STATUS_LABELS: ReadonlyArray<string> = Object.values(DISPLAY).map(
81 display => display.label
82 );
83
84 +export const RECOVERY_RUNBOOK =
85 + 'https://github.com/ComposioHQ/composio/blob/next/ts/docs/internal/release.md#recover-a-failed-release';
86 +
87 /** How to resume a failed stage. */
88 const RECOVERY: Record<Stage, string> = {
89 request: 'Open the run and choose "Re-run failed jobs", or request the release again.',
87 - review: 'Open the run and choose "Re-run failed jobs"; creating the tag is safe to repeat.',
90 + review: `If GitHub failed, open the run and choose "Re-run failed jobs"; creating the tag is safe to repeat. A re-run uses the gate as it was before the merge, so if the gate itself is wrong, fix it on \`next\` and dispatch **SDK release** with action \`regate\`: ${RECOVERY_RUNBOOK}`,
91 publish:
92 'Open the run and choose "Re-run failed jobs"; a re-run uploads only the files the registries are missing. If the approved candidates expired or a registry serves different bytes, add changesets and request a new release.',
93 };
@@ -97,14 +100,14 @@ export const describe = (state: ReleaseState) =>
100 Waiting: ({ pull }) =>
101 `Another SDK release is in progress: ${pull}. Request this release again after it finishes.`,
102 Blocked: ({ release }) =>
100 - `The release planned in run ${release} merged into \`next\` but was never tagged. Re-run its tag job, or revert its release PR on \`next\`, then request this release again.`,
103 + `The release planned in run ${release} merged into \`next\` but was never tagged. If a gate bug refused it and the fix is on \`next\`, dispatch **SDK release** with action \`regate\`; otherwise revert its release PR on \`next\`. Then request this release again. See ${RECOVERY_RUNBOOK}`,
104 Empty: () => 'Nothing to release: no pending changesets for the selected languages.',
105 InReview: ({ pull }) =>
106 `Release PR: ${pull}\n\nA writer other than the requester approves it. Merging it tags and publishes the release.`,
107 Abandoned: ({ pull }) =>
108 `${pull} closed without merging, so nothing was tagged or published. Request a new release when ready.`,
109 Refused: ({ pull, reason }) =>
107 - `${pull} merged, but it failed the release gate, so nothing was tagged or published.\n\nReason: ${reason}\n\nRevert the release PR on \`next\`, then request the release again.`,
110 + `${pull} merged, but it failed the release gate, so nothing was tagged or published.\n\nReason: ${reason}\n\nRevert the release PR on \`next\`, then request the release again. If the gate itself was wrong, fix it on \`next\` and dispatch **SDK release** with action \`regate\` instead: ${RECOVERY_RUNBOOK}`,
111 Tagged: ({ tag }) => `Tagged \`${tag}\`. The tag run publishes the reviewed files.`,
112 Published: ({ versions }) =>
113 ['Published:', '', ...versions.map(({ name, version }) => `- ${name} ${version}`)].join('\n'),
test/sdk-release-approval.test.ts
+35 -5
@@ -68,6 +68,7 @@ describe('source tag', () => {
68 test('required checks on a later page of more than 100 check runs still tag the head', async () => {
69 const { fetcher, writes } = fakeController();
70 const unrelated = Array.from({ length: 100 }, (_, index) => ({
71 + id: 100 + index,
72 name: `matrix job ${index}`,
73 head_sha: head,
74 app: { slug: 'github-actions' },
@@ -105,8 +106,18 @@ describe('source tag', () => {
106 expect(await issueOf({ branchSetter: 'writer' })).toEqual(Option.none());
107 });
108
108 - test('a beta is tagged without the docs check, which never runs on a plan-only PR', async () => {
109 - const { fetcher, writes } = fakeController({ beta: true, docs: 'missing' });
109 + test('a beta is tagged without either docs check, which never run on a plan-only PR', async () => {
110 + const { fetcher, writes } = fakeController({
111 + beta: true,
112 + docs: 'missing',
113 + rerunFailed: 'typescript-check',
114 + });
115 + expect(await tag(fetcher)).toEqual(tagged);
116 + expect(writes).toEqual([tagWrite]);
117 + });
118 +
119 + test('a stable release no longer needs the pull-request docs check, which skips release heads', async () => {
120 + const { fetcher, writes } = fakeController({ rerunFailed: 'typescript-check' });
121 expect(await tag(fetcher)).toEqual(tagged);
122 expect(writes).toEqual([tagWrite]);
123 });
@@ -130,9 +141,14 @@ describe('source tag', () => {
141 ['the head is not on the planned source', { headParent: merge }, 'release App commit'],
142 ['the candidate build failed', { failedCandidate: true }, 'SDK candidate (typescript)'],
143 ['the smoke test failed', { failedSmoke: true }, 'SDK candidate smoke (typescript)'],
133 - ['the docs check failed', { docs: 'failure' }, 'typescript-check'],
134 - ['the docs check is pending', { docs: 'pending' }, 'typescript-check'],
135 - ['the docs check is missing', { docs: 'missing' }, 'typescript-check'],
144 + ['the docs check failed', { docs: 'failure' }, 'SDK candidate docs'],
145 + ['the docs check is pending', { docs: 'pending' }, 'SDK candidate docs'],
146 + ['the docs check is missing', { docs: 'missing' }, 'SDK candidate docs'],
147 + [
148 + 'a re-run of a passed check failed',
149 + { rerunFailed: 'SDK candidate (typescript)' },
150 + 'SDK candidate (typescript)',
151 + ],
152 ])(
153 'when %s, the release is refused, no tag is created and the PR is told to revert',
154 async (_name, options, reason) => {
@@ -160,6 +176,20 @@ describe('source tag', () => {
176 expect(writes).toEqual([]);
177 });
178
179 + test('a pull without `merged` is a contract failure, not an abandoned release', async () => {
180 + const { fetcher, writes } = fakeController();
181 + const withoutMerged: typeof fetcher = async (input, init) => {
182 + const response = await fetcher(input, init);
183 + if (new URL(String(input)).pathname !== '/repos/ComposioHQ/composio/pulls/9') return response;
184 + const { merged: _merged, ...rest } = (await response.json()) as Record<string, unknown>;
185 + return Response.json(rest);
186 + };
187 + await expect(tag(withoutMerged)).rejects.toThrow(
188 + /GET \/repos\/ComposioHQ\/composio\/pulls\/9[\s\S]*merged/
189 + );
190 + expect(writes).toEqual([]);
191 + });
192 +
193 test('an existing matching tag is reused and a tag on another commit is refused', async () => {
194 const matching = fakeController({ existingTag: head });
195 expect(await tag(matching.fetcher)).toEqual(tagged);
test/sdk-release-approved-candidate.test.ts
+21
@@ -179,6 +179,13 @@ test.each<
179 { createdAt: '2026-11-03T00:08:00Z' },
180 'sdk-candidate-python was created at 2026-11-03T00:08:00Z, outside its upload step',
181 ],
182 + [
183 + 'an artifact created two seconds after its upload step ended',
184 + [releaseRun(41)],
185 + false,
186 + { createdAt: '2026-11-03T00:06:02Z' },
187 + 'sdk-candidate-python was created at 2026-11-03T00:06:02Z, outside its upload step',
188 + ],
189 [
190 'a build job that did not succeed',
191 [releaseRun(41)],
@@ -198,6 +205,20 @@ test.each<
205 expect(await Bun.file(`${target}/${wheel}`).exists()).toBe(false);
206 });
207
208 +// GitHub reports both times to the second, so a real artifact can land on either boundary second.
209 +test.each(['2026-11-03T00:03:59Z', '2026-11-03T00:06:00Z', '2026-11-03T00:06:01Z'])(
210 + 'adopts an artifact created at %s, within a second of its 00:04:00–00:06:00 upload step',
211 + async createdAt => {
212 + const archive = await approvedArchive();
213 + const target = `${await directories.create()}/python`;
214 + const approved = await runRelease(
215 + adoptApprovedCandidate(head, 'python', target),
216 + fakeGitHub(archive, [releaseRun(41)], false, { createdAt })
217 + );
218 + expect(approved).toEqual({ run: 41, artifactId: 77, digest: archive.digest });
219 + }
220 +);
221 +
222 test('a smoke-only re-run attempt still adopts the candidate its first attempt built', async () => {
223 const archive = await approvedArchive();
224 const target = `${await directories.create()}/python`;
test/sdk-release-candidate-pin.test.ts
+2 -61
@@ -7,12 +7,11 @@ import {
7 temporaryDirectories,
8 writeText,
9 } from './sdk-release-harness';
10 -import { batch } from './sdk-release-controller-fixture';
10 +import { batch, candidateRoutes, head } from './sdk-release-controller-fixture';
11
12 const directories = temporaryDirectories('sdk-candidate-pin-');
13 afterEach(() => directories.cleanup());
14
15 -const head = 'b'.repeat(40);
15 const tarball = 'composio-core-1.0.1.tgz';
16
17 /** The archive release-PR run 41 uploaded for `@composio/core@1.0.1`. */
@@ -50,65 +49,7 @@ const pinAttempt = async (
49 JSON.stringify({ name: '@composio/core', version: '1.0.1' })
50 );
51 await writeText(`${directory}/.github/sdk-release-plan.json`, JSON.stringify(batch));
53 - const app = 'sdk-release-app[bot]';
54 - const routes = {
55 - [`/commits/${head}`]: {
56 - author: { login: options.headAuthor ?? app },
57 - committer: { login: 'web-flow' },
58 - commit: { verification: { verified: true } },
59 - parents: [{ sha: batch.inputBase }],
60 - },
61 - '/activity': [{ after: head, actor: { login: app } }],
62 - '/actions/workflows/sdk.release.candidates.yml/runs': {
63 - workflow_runs: [
64 - {
65 - id: 41,
66 - path: '.github/workflows/sdk.release.candidates.yml',
67 - head_branch: 'sdk-release/batch-8',
68 - head_sha: head,
69 - event: 'pull_request',
70 - repository: { full_name: 'ComposioHQ/composio' },
71 - status: 'completed',
72 - conclusion: 'success',
73 - created_at: '2026-11-03T00:00:00Z',
74 - run_attempt: 1,
75 - html_url: 'https://github.com/ComposioHQ/composio/actions/runs/41',
76 - },
77 - ],
78 - },
79 - '/actions/runs/41/jobs': {
80 - jobs: [
81 - {
82 - name: 'SDK candidate (typescript)',
83 - status: 'completed',
84 - conclusion: 'success',
85 - started_at: '2026-11-03T00:01:00Z',
86 - completed_at: '2026-11-03T00:10:00Z',
87 - steps: [
88 - {
89 - name: 'Retain candidate bytes for publication',
90 - conclusion: 'success',
91 - started_at: '2026-11-03T00:04:00Z',
92 - completed_at: '2026-11-03T00:06:00Z',
93 - },
94 - ],
95 - },
96 - ],
97 - },
98 - '/actions/runs/41/artifacts': {
99 - artifacts: [
100 - {
101 - id: 77,
102 - name: 'sdk-candidate-typescript',
103 - digest: archive.digest,
104 - expired: options.expired ?? false,
105 - created_at: '2026-11-03T00:05:00Z',
106 - expires_at: '2099-12-01T00:00:00Z',
107 - workflow_run: { id: 41, head_sha: head },
108 - },
109 - ],
110 - },
111 - };
52 + const routes = candidateRoutes(archive.digest, options);
53 const preload = `${directory}/fetch.ts`;
54 await writeText(
55 preload,
test/sdk-release-candidate-registry.test.ts new
+358
@@ -0,0 +1,358 @@
1 +import { afterEach, describe, expect, test } from 'bun:test';
2 +import { Effect } from 'effect';
3 +import { CANDIDATE_MANIFEST } from '../scripts/sdk-release/artifacts';
4 +import {
5 + assertCandidateVersions,
6 + installCandidateDocs,
7 + loadCandidatePackages,
8 + serveCandidateRegistry,
9 +} from '../scripts/sdk-release/candidate-registry';
10 +import { tarballName } from '../scripts/sdk-release/candidates';
11 +import { CHANNELS } from '../scripts/sdk-release/channel';
12 +import { run, withoutReleaseTokens } from '../scripts/sdk-release/runtime';
13 +import type { ReleaseBatch } from '../scripts/sdk-release/source';
14 +import { batch } from './sdk-release-controller-fixture';
15 +import {
16 + json,
17 + makeExecutable,
18 + readText,
19 + runRelease,
20 + temporaryDirectories,
21 + writeText,
22 + type Fetch,
23 +} from './sdk-release-harness';
24 +
25 +const directories = temporaryDirectories('sdk-candidate-registry-');
26 +afterEach(directories.cleanup);
27 +
28 +const PLANNED = '@composio/release-fixture';
29 +const CANDIDATE = '1.1.0';
30 +const UPSTREAM = 'https://registry.npmjs.org';
31 +
32 +const exec = (cwd: string, executable: string, args: ReadonlyArray<string>) =>
33 + runRelease(run(executable, args, { cwd, env: withoutReleaseTokens }));
34 +
35 +/** Packs `package.json` plus an index file into `<root>/<file>` and returns its bytes. */
36 +const pack = async (root: string, file: string, manifest: Record<string, unknown>) => {
37 + const staging = await directories.create();
38 + await writeText(`${staging}/package/package.json`, JSON.stringify(manifest));
39 + await writeText(`${staging}/package/index.js`, `export const version = '${manifest.version}';\n`);
40 + await exec(staging, 'tar', ['-czf', `${root}/${file}`, 'package']);
41 + return new Uint8Array(await Bun.file(`${root}/${file}`).arrayBuffer());
42 +};
43 +
44 +const sha256 = (bytes: Uint8Array) => new Bun.CryptoHasher('sha256').update(bytes).digest('hex');
45 +const sha512 = (bytes: Uint8Array) =>
46 + `sha512-${new Bun.CryptoHasher('sha512').update(bytes).digest('base64')}`;
47 +
48 +/** A downloaded TypeScript candidate holding `@composio/release-fixture@1.1.0`. */
49 +const candidateDirectory = async () => {
50 + const directory = await directories.create();
51 + const file = tarballName(PLANNED, CANDIDATE);
52 + const bytes = await pack(directory, file, { name: PLANNED, version: CANDIDATE });
53 + await writeText(
54 + `${directory}/${CANDIDATE_MANIFEST}`,
55 + JSON.stringify({
56 + sourceSha: 'b'.repeat(40),
57 + producerRun: 41,
58 + language: 'typescript',
59 + files: [{ name: file, sha256: sha256(bytes), size: bytes.length }],
60 + })
61 + );
62 + return { directory, file, bytes };
63 +};
64 +
65 +const typescriptBatch: ReleaseBatch = {
66 + ...batch,
67 + plan: {
68 + ...batch.plan,
69 + releases: [{ ...batch.plan.releases[0], name: PLANNED, newVersion: CANDIDATE }],
70 + },
71 +};
72 +
73 +/**
74 + * A fake npm registry. Packuments name tarballs under `tarballOrigin()`, which a test points at
75 + * the candidate registry, so every download goes through it and nothing reaches the network.
76 + */
77 +const fakeUpstream = (
78 + tarballs: Record<string, { manifest: Record<string, unknown>; bytes: Uint8Array<ArrayBuffer> }>,
79 + tarballOrigin: () => string
80 +) => {
81 + const requests: string[] = [];
82 + const fetcher: Fetch = async input => {
83 + const url = new URL(String(input));
84 + requests.push(url.pathname);
85 + const name = decodeURIComponent(url.pathname).slice(1);
86 + const versions = Object.values(tarballs).filter(({ manifest }) => manifest.name === name);
87 + if (url.origin === UPSTREAM && versions.length)
88 + return json({
89 + name,
90 + 'dist-tags': { latest: versions.at(-1)?.manifest.version },
91 + versions: Object.fromEntries(
92 + versions.map(({ manifest, bytes }) => [
93 + manifest.version,
94 + {
95 + ...manifest,
96 + dist: {
97 + tarball: `${tarballOrigin()}/${name}/-/${name.split('/').at(-1)}-${manifest.version}.tgz`,
98 + integrity: sha512(bytes),
99 + },
100 + },
101 + ])
102 + ),
103 + });
104 + const tarball = tarballs[decodeURIComponent(url.pathname)];
105 + if (url.origin === UPSTREAM && tarball) return new Response(tarball.bytes);
106 + return json({ error: 'Not found' }, 404);
107 + };
108 + return { fetcher, requests };
109 +};
110 +
111 +describe('candidate registry', () => {
112 + test('serves a planned package from its candidate file and proxies every other package', async () => {
113 + const candidate = await candidateDirectory();
114 + const upstream = fakeUpstream({}, () => UPSTREAM);
115 + const leftPad = { name: 'left-pad', 'dist-tags': { latest: '1.3.0' }, versions: {} };
116 + const fetcher: Fetch = async (input, init) =>
117 + new URL(String(input)).pathname === '/left-pad'
118 + ? json(leftPad)
119 + : upstream.fetcher(input, init);
120 + const responses = await runRelease(
121 + Effect.scoped(
122 + Effect.gen(function* () {
123 + const packages = yield* loadCandidatePackages(candidate.directory, [
124 + { name: PLANNED, newVersion: CANDIDATE },
125 + ]);
126 + const origin = yield* serveCandidateRegistry(packages);
127 + return yield* Effect.promise(async () => {
128 + const packument = await (await fetch(`${origin}/@composio%2frelease-fixture`)).json();
129 + const dist = packument.versions[CANDIDATE].dist;
130 + return {
131 + packument,
132 + tarballUrl: dist.tarball as string,
133 + tarball: new Uint8Array(await (await fetch(dist.tarball)).arrayBuffer()),
134 + proxied: await (await fetch(`${origin}/left-pad`)).json(),
135 + published: (
136 + await fetch(`${origin}/@composio/release-fixture/-/release-fixture-1.0.0.tgz`)
137 + ).status,
138 + origin,
139 + };
140 + });
141 + })
142 + ),
143 + fetcher
144 + );
145 + expect(responses.packument['dist-tags']).toEqual({ latest: CANDIDATE });
146 + expect(Object.keys(responses.packument.versions)).toEqual([CANDIDATE]);
147 + expect(responses.packument.versions[CANDIDATE]).toMatchObject({
148 + name: PLANNED,
149 + version: CANDIDATE,
150 + dist: { integrity: sha512(candidate.bytes) },
151 + });
152 + expect(responses.tarballUrl.startsWith(responses.origin)).toBe(true);
153 + expect(responses.tarball).toEqual(candidate.bytes);
154 + expect(responses.proxied).toEqual(leftPad);
155 + // A planned package never falls through to the public registry, not even an older version.
156 + expect(responses.published).toBe(404);
157 + expect(upstream.requests).toEqual([]);
158 + });
159 +
160 + test('a candidate whose bytes differ from its manifest is refused before anything is installed', async () => {
161 + const candidate = await candidateDirectory();
162 + await Bun.write(`${candidate.directory}/${candidate.file}`, 'tampered');
163 + const docs = await directories.create();
164 + const manifest = JSON.stringify({ dependencies: { [PLANNED]: '1.0.0' } });
165 + await writeText(`${docs}/package.json`, manifest);
166 + const bin = await directories.create();
167 + await writeText(`${bin}/bun`, `#!/bin/sh\necho "$@" >> ${bin}/bun.log\n`);
168 + await makeExecutable(`${bin}/bun`);
169 + const previous = process.env.PATH;
170 + try {
171 + process.env.PATH = `${bin}:${previous}`;
172 + await expect(
173 + runRelease(installCandidateDocs(docs, typescriptBatch, candidate.directory))
174 + ).rejects.toThrow(`Candidate checksum mismatch: ${candidate.file}`);
175 + } finally {
176 + process.env.PATH = previous;
177 + }
178 + expect(await Bun.file(`${bin}/bun.log`).exists()).toBe(false);
179 + expect(await readText(`${docs}/package.json`)).toBe(manifest);
180 + });
181 +});
182 +
183 +describe('docs install against the candidate', () => {
184 + test('every copy of a planned package, nested ones included, resolves to the candidate version', async () => {
185 + const candidate = await candidateDirectory();
186 + const published = await directories.create();
187 + const tarball = async (name: string, version: string, extra: Record<string, unknown> = {}) => {
188 + const manifest = { name, version, ...extra };
189 + const file = `${name.split('/').at(-1)}-${version}.tgz`;
190 + return [
191 + `/${name}/-/${file}`,
192 + { manifest, bytes: await pack(published, file.replace('/', '-'), manifest) },
193 + ] as const;
194 + };
195 + const tarballs = Object.fromEntries([
196 + await tarball(PLANNED, '1.0.0'),
197 + await tarball(PLANNED, '0.9.0'),
198 + // Pins an older planned version, so the hoisted install nests its own copy.
199 + await tarball('consumer-fixture', '1.0.0', { dependencies: { [PLANNED]: '0.9.0' } }),
200 + ]);
201 + let origin = '';
202 + const upstream = fakeUpstream(tarballs, () => origin);
203 + const docs = await directories.create();
204 + await writeText(
205 + `${docs}/package.json`,
206 + JSON.stringify({
207 + name: 'docs-fixture',
208 + private: true,
209 + dependencies: { [PLANNED]: '1.0.0', 'consumer-fixture': '1.0.0' },
210 + })
211 + );
212 +
213 + // The committed lock pins the published versions, as the docs lock does before release.
214 + const cache = await directories.create();
215 + await runRelease(
216 + Effect.scoped(
217 + Effect.gen(function* () {
218 + origin = yield* serveCandidateRegistry([]);
219 + yield* run('bun', ['install'], {
220 + cwd: docs,
221 + env: {
222 + ...withoutReleaseTokens,
223 + NPM_CONFIG_REGISTRY: origin,
224 + BUN_INSTALL_CACHE_DIR: cache,
225 + },
226 + });
227 + })
228 + ),
229 + upstream.fetcher
230 + );
231 + const nested = `${docs}/node_modules/consumer-fixture/node_modules/${PLANNED}/package.json`;
232 + expect((await Bun.file(nested).json()).version).toBe('0.9.0');
233 + const committedLock = await readText(`${docs}/bun.lock`);
234 +
235 + upstream.requests.length = 0;
236 + await runRelease(
237 + installCandidateDocs(docs, typescriptBatch, candidate.directory),
238 + upstream.fetcher
239 + );
240 +
241 + expect((await Bun.file(`${docs}/node_modules/${PLANNED}/package.json`).json()).version).toBe(
242 + CANDIDATE
243 + );
244 + expect(await Bun.file(nested).exists()).toBe(false);
245 + expect(await readText(`${docs}/bun.lock`)).not.toBe(committedLock);
246 + expect(upstream.requests.filter(path => decodeURIComponent(path).includes(PLANNED))).toEqual(
247 + []
248 + );
249 + await runRelease(
250 + assertCandidateVersions(
251 + `${docs}/node_modules`,
252 + [{ name: PLANNED, newVersion: CANDIDATE }],
253 + [PLANNED]
254 + )
255 + );
256 + });
257 +
258 + test('the version check names every installed copy that kept another version', async () => {
259 + const nodeModules = `${await directories.create()}/node_modules`;
260 + const at = (directory: string, version: string) =>
261 + writeText(`${directory}/package.json`, JSON.stringify({ name: PLANNED, version }));
262 + await at(`${nodeModules}/${PLANNED}`, CANDIDATE);
263 + await at(`${nodeModules}/consumer-fixture/node_modules/${PLANNED}`, '1.0.0');
264 + await writeText(`${nodeModules}/consumer-fixture/package.json`, '{"version":"1.0.0"}');
265 + const releases = [{ name: PLANNED, newVersion: CANDIDATE }];
266 +
267 + await expect(
268 + runRelease(assertCandidateVersions(nodeModules, releases, [PLANNED]))
269 + ).rejects.toThrow(`consumer-fixture/node_modules/${PLANNED} is 1.0.0`);
270 +
271 + await at(`${nodeModules}/consumer-fixture/node_modules/${PLANNED}`, CANDIDATE);
272 + await runRelease(assertCandidateVersions(nodeModules, releases, [PLANNED]));
273 + await expect(
274 + runRelease(assertCandidateVersions(await directories.create(), releases, [PLANNED]))
275 + ).rejects.toThrow(`${PLANNED} is not installed`);
276 + });
277 +
278 + test('a Python-only stable plan installs the committed docs lock from npm unchanged', async () => {
279 + const docs = await directories.create();
280 + const manifest = JSON.stringify({ dependencies: { '@composio/core': '0.29.0' } });
281 + await writeText(`${docs}/package.json`, manifest);
282 + const bin = await directories.create();
283 + await writeText(
284 + `${bin}/bun`,
285 + `#!/bin/sh\necho "$PWD|$*|registry=$NPM_CONFIG_REGISTRY" >> ${bin}/bun.log\n`
286 + );
287 + await makeExecutable(`${bin}/bun`);
288 + const python: ReleaseBatch = {
289 + ...batch,
290 + plan: {
291 + ...batch.plan,
292 + choices: { ...batch.plan.choices, typescript: 'skip', python: 'auto' },
293 + releases: [
294 + {
295 + name: '@composio/python-sdk',
296 + type: 'minor',
297 + oldVersion: '0.31.0',
298 + newVersion: '0.32.0',
299 + changesets: [],
300 + language: 'python',
301 + },
302 + ],
303 + },
304 + };
305 + const previous = process.env.PATH;
306 + try {
307 + process.env.PATH = `${bin}:${previous}`;
308 + await runRelease(installCandidateDocs(docs, python, `${docs}/no-candidate`));
309 + } finally {
310 + process.env.PATH = previous;
311 + }
312 + const realDocs = (await exec(docs, 'pwd', ['-P'])).trim();
313 + expect((await readText(`${bin}/bun.log`)).trim()).toBe(
314 + `${realDocs}|install --frozen-lockfile|registry=`
315 + );
316 + expect(await readText(`${docs}/package.json`)).toBe(manifest);
317 + });
318 +});
319 +
320 +describe('docs workflows', () => {
321 + const workflow = async (name: string) =>
322 + Bun.YAML.parse(await readText(`.github/workflows/${name}`)) as {
323 + jobs: Record<string, Record<string, unknown>>;
324 + };
325 + /** Reads the only condition shape these jobs use: a negated head-branch prefix. */
326 + const headCondition = (condition: unknown) => {
327 + const match = /^\$\{\{ !startsWith\(github\.head_ref, '([^']+)'\) \}\}$/.exec(
328 + String(condition)
329 + );
330 + expect(match).not.toBeNull();
331 + return (head: string) => !head.startsWith(match?.[1] ?? '');
332 + };
333 +
334 + test.each([
335 + ['docs-typescript-check.yml', 'typescript-check'],
336 + ['docs-tests.yml', 'test'],
337 + ])('%s skips release PR heads, which pin versions npm does not serve yet', async (file, job) => {
338 + const runsOn = headCondition((await workflow(file)).jobs[job].if);
339 + expect(runsOn('sdk-release/batch-42589989280')).toBe(false);
340 + expect(runsOn('feat/docs-change')).toBe(true);
341 + expect(runsOn('sdk-release-notes')).toBe(true);
342 + });
343 +
344 + test('the candidate docs job runs on stable release PRs only, with no credentials', async () => {
345 + const { jobs } = await workflow('sdk.release.candidates.yml');
346 + const docs = jobs.docs;
347 + expect(docs.name).toBe('SDK candidate docs');
348 + // The stable gate requires the check this job reports, under the same name.
349 + expect(CHANNELS.stable.extraChecks.join()).toBe(String(docs.name));
350 + expect(docs.needs).toEqual(['select-candidates', 'candidate']);
351 + expect(docs.if).toBe(
352 + "${{ !cancelled() && needs.select-candidates.outputs.channel == 'stable' }}"
353 + );
354 + expect(docs.permissions).toEqual({ contents: 'read' });
355 + expect(docs['timeout-minutes']).toBeGreaterThan(0);
356 + expect(JSON.stringify(docs)).not.toContain('secrets.');
357 + });
358 +});
test/sdk-release-controller-fixture.ts
+87 -7
@@ -66,6 +66,8 @@ export const releaseFiles = [
66 export interface ControllerOptions {
67 /** `next` carries batch 8's plan without its tag: a release merged and failed its gate. */
68 readonly untaggedNext?: boolean;
69 + /** `next` at the merge commit carries no release plan. */
70 + readonly noPlanOnNext?: boolean;
71 /** Serve batch 8 as a beta release PR. */
72 readonly beta?: boolean;
73 readonly deletedReviewer?: boolean;
@@ -75,10 +77,13 @@ export interface ControllerOptions {
77 readonly existingTag?: string;
78 readonly failedCandidate?: boolean;
79 readonly failedSmoke?: boolean;
80 + /** A re-run of this check failed after its first run succeeded. */
81 + readonly rerunFailed?: string;
82 readonly closedUnmerged?: boolean;
83 readonly existingBranch?: boolean;
84 /** Head branch of a release PR that is already open into next. */
85 readonly openRelease?: string;
86 + /** The `SDK candidate docs` check on the head. */
87 readonly docs?: 'success' | 'failure' | 'pending' | 'missing';
88 /** Who authored the release PR head; the release App by default. */
89 readonly headAuthor?: string;
@@ -93,16 +98,19 @@ export interface ControllerOptions {
98 export function fakeController(options: ControllerOptions = {}) {
99 const writes: { method: string; path: string; body: unknown }[] = [];
100 const merged = !options.closedUnmerged;
96 - const pull = () => ({
101 + /** A pull as list endpoints return it: GitHub sends `merged` only on the detail endpoint. */
102 + const listedPull = () => ({
103 number: 9,
104 html_url: 'https://github.com/ComposioHQ/composio/pull/9',
105 state: 'closed',
100 - merged,
106 user: { login: `${APP_SLUG}[bot]` },
107 head: { sha: head, ref: 'sdk-release/batch-8', repo: { full_name: 'ComposioHQ/composio' } },
108 base: { ref: 'next' },
109 });
105 - const check = (name: string, conclusion: string | null) => ({
110 + const pull = () => ({ ...listedPull(), merged });
111 + /** GitHub numbers check runs in creation order, so a re-run has a higher `id`. */
112 + const check = (name: string, conclusion: string | null, id = 1) => ({
113 + id,
114 name,
115 head_sha: head,
116 app: { slug: 'github-actions' },
@@ -123,17 +131,18 @@ export function fakeController(options: ControllerOptions = {}) {
131 throw new Error(`Unexpected write ${method} ${path}`);
132 }
133 if (path === '/orgs/ComposioHQ/memberships/requester') return response({ state: 'active' });
134 + // The closed release PRs from batch 8's branch, as a regate looks them up.
135 + if (path.startsWith('/pulls?state=closed&')) return response([listedPull()]);
136 if (path.startsWith('/pulls?'))
137 return response(
138 options.openRelease
139 ? [
140 {
131 - ...pull(),
141 + ...listedPull(),
142 number: 5,
143 html_url: 'https://github.com/ComposioHQ/composio/pull/5',
144 state: 'open',
135 - merged: false,
136 - head: { ...pull().head, ref: options.openRelease },
145 + head: { ...listedPull().head, ref: options.openRelease },
146 },
147 ]
148 : []
@@ -159,10 +168,11 @@ export function fakeController(options: ControllerOptions = {}) {
168 ? []
169 : [
170 check(
162 - 'typescript-check',
171 + 'SDK candidate docs',
172 options.docs === 'pending' ? null : (options.docs ?? 'success')
173 ),
174 ]),
175 + ...(options.rerunFailed ? [check(options.rerunFailed, 'failure', 2)] : []),
176 ],
177 });
178 if (path === `/commits/${head}`)
@@ -199,6 +209,7 @@ export function fakeController(options: ControllerOptions = {}) {
209 : [{ sha: 'd'.repeat(40) }],
210 });
211 if (path.startsWith('/contents/')) {
212 + if (options.noPlanOnNext && url.searchParams.get('ref') === merge) return response({}, 404);
213 const filename = url.pathname.split('/contents/')[1];
214 const file = (options.beta ? betaFiles : releaseFiles).find(file => file.path === filename);
215 const data = url.searchParams.get('ref') === base ? file?.before : file?.after;
@@ -219,3 +230,72 @@ export function fakeController(options: ControllerOptions = {}) {
230 };
231 return { fetcher, writes };
232 }
233 +
234 +/**
235 + * The reads a tag run makes to pin release-PR run 41's candidate for batch 8, keyed by path
236 + * suffix. `digest` is the uploaded archive's digest.
237 + */
238 +export const candidateRoutes = (
239 + digest: string,
240 + options: { expired?: boolean; headAuthor?: string } = {}
241 +) => {
242 + const app = 'sdk-release-app[bot]';
243 + return {
244 + [`/commits/${head}`]: {
245 + author: { login: options.headAuthor ?? app },
246 + committer: { login: 'web-flow' },
247 + commit: { verification: { verified: true } },
248 + parents: [{ sha: batch.inputBase }],
249 + },
250 + '/activity': [{ after: head, actor: { login: app } }],
251 + '/actions/workflows/sdk.release.candidates.yml/runs': {
252 + workflow_runs: [
253 + {
254 + id: 41,
255 + path: '.github/workflows/sdk.release.candidates.yml',
256 + head_branch: 'sdk-release/batch-8',
257 + head_sha: head,
258 + event: 'pull_request',
259 + repository: { full_name: 'ComposioHQ/composio' },
260 + status: 'completed',
261 + conclusion: 'success',
262 + created_at: '2026-11-03T00:00:00Z',
263 + run_attempt: 1,
264 + html_url: 'https://github.com/ComposioHQ/composio/actions/runs/41',
265 + },
266 + ],
267 + },
268 + '/actions/runs/41/jobs': {
269 + jobs: [
270 + {
271 + name: 'SDK candidate (typescript)',
272 + status: 'completed',
273 + conclusion: 'success',
274 + started_at: '2026-11-03T00:01:00Z',
275 + completed_at: '2026-11-03T00:10:00Z',
276 + steps: [
277 + {
278 + name: 'Retain candidate bytes for publication',
279 + conclusion: 'success',
280 + started_at: '2026-11-03T00:04:00Z',
281 + completed_at: '2026-11-03T00:06:00Z',
282 + },
283 + ],
284 + },
285 + ],
286 + },
287 + '/actions/runs/41/artifacts': {
288 + artifacts: [
289 + {
290 + id: 77,
291 + name: 'sdk-candidate-typescript',
292 + digest: digest,
293 + expired: options.expired ?? false,
294 + created_at: '2026-11-03T00:05:00Z',
295 + expires_at: '2099-12-01T00:00:00Z',
296 + workflow_run: { id: 41, head_sha: head },
297 + },
298 + ],
299 + },
300 + };
301 +};
test/sdk-release-github-client.test.ts new
+132
@@ -0,0 +1,132 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { Effect, Schema } from 'effect';
3 +import { GitHub, request } from '../scripts/sdk-release/github';
4 +import { json, runRelease, type Fetch } from './sdk-release-harness';
5 +
6 +const Ref = Schema.Struct({ ref: Schema.String });
7 +
8 +/** Answers each request with the next response and counts the requests. */
9 +const scripted = (...responses: Array<() => Response | Promise<Response>>) => {
10 + const seen: string[] = [];
11 + const fetcher: Fetch = async (input, init) => {
12 + seen.push(`${init?.method ?? 'GET'} ${new URL(String(input)).pathname}`);
13 + const next = responses[Math.min(seen.length, responses.length) - 1];
14 + return next();
15 + };
16 + return { fetcher, seen };
17 +};
18 +
19 +const githubError = (status: number, message: string, headers: Record<string, string> = {}) =>
20 + new Response(JSON.stringify({ message, documentation_url: 'https://docs.github.com' }), {
21 + status,
22 + headers: { 'x-github-request-id': 'C766:174D:1', ...headers },
23 + });
24 +
25 +const call = (
26 + fetcher: Fetch,
27 + method: 'GET' | 'POST' = 'GET',
28 + policy: Parameters<typeof GitHub.layer>[1] = { baseDelayMs: 1 }
29 +) =>
30 + runRelease(
31 + request(
32 + method,
33 + '/repos/ComposioHQ/composio/git/refs',
34 + Ref,
35 + method === 'GET' ? undefined : {}
36 + ).pipe(Effect.provide(GitHub.layer('token', policy))),
37 + fetcher
38 + );
39 +
40 +describe('GitHub client', () => {
41 + test("a 422 reports GitHub's message and request ID and is not retried", async () => {
42 + const github = scripted(() => githubError(422, 'Reference already exists'));
43 + const failure = call(github.fetcher, 'POST');
44 + await expect(failure).rejects.toThrow('Reference already exists');
45 + await expect(failure).rejects.toThrow('C766:174D:1');
46 + expect(github.seen).toHaveLength(1);
47 + });
48 +
49 + test('a GET that returns 502 succeeds on the retry', async () => {
50 + const github = scripted(
51 + () => githubError(502, 'Server Error'),
52 + () => json({ ref: 'refs/heads/next' })
53 + );
54 + expect(await call(github.fetcher)).toEqual({ ref: 'refs/heads/next' });
55 + expect(github.seen).toHaveLength(2);
56 + });
57 +
58 + test('a POST that returns 502 is not retried, since GitHub may have applied it', async () => {
59 + const github = scripted(() => githubError(502, 'Server Error'));
60 + const failure = call(github.fetcher, 'POST');
61 + await expect(failure).rejects.toThrow('(502): Server Error');
62 + await expect(failure).rejects.toThrow('C766:174D:1');
63 + expect(github.seen).toHaveLength(1);
64 + });
65 +
66 + test('a rate-limited write waits for Retry-After and retries', async () => {
67 + const github = scripted(
68 + () =>
69 + githubError(403, 'You have exceeded a secondary rate limit.', {
70 + 'x-ratelimit-remaining': '0',
71 + 'retry-after': '1',
72 + }),
73 + () => json({ ref: 'refs/tags/sdk-release/8' })
74 + );
75 + const started = performance.now();
76 + expect(await call(github.fetcher, 'POST')).toEqual({ ref: 'refs/tags/sdk-release/8' });
77 + expect(performance.now() - started).toBeGreaterThanOrEqual(950);
78 + expect(github.seen).toHaveLength(2);
79 + });
80 +
81 + test("a 403 that is not a rate limit fails at once with GitHub's message", async () => {
82 + const github = scripted(() => githubError(403, 'Resource not accessible by integration'));
83 + await expect(call(github.fetcher)).rejects.toThrow(
84 + '(403): Resource not accessible by integration'
85 + );
86 + expect(github.seen).toHaveLength(1);
87 + });
88 +
89 + test('a rate limit asking for a longer wait than the policy allows gives up at once', async () => {
90 + const github = scripted(() => githubError(429, 'Too Many Requests', { 'retry-after': '3600' }));
91 + await expect(call(github.fetcher)).rejects.toThrow('gave up after 1 attempt');
92 + expect(github.seen).toHaveLength(1);
93 + });
94 +
95 + test('repeated 503s stop after the attempt budget', async () => {
96 + const github = scripted(() => githubError(503, 'Service Unavailable'));
97 + await expect(call(github.fetcher)).rejects.toThrow('after 5 attempts');
98 + expect(github.seen).toHaveLength(5);
99 + });
100 +
101 + test('a request that times out is retried', async () => {
102 + const github = scripted(
103 + () => new Promise<Response>(() => {}),
104 + () => json({ ref: 'refs/heads/next' })
105 + );
106 + expect(await call(github.fetcher, 'GET', { baseDelayMs: 1, timeout: '50 millis' })).toEqual({
107 + ref: 'refs/heads/next',
108 + });
109 + expect(github.seen).toHaveLength(2);
110 + });
111 +
112 + test('a response whose body stalls after its headers times out and is retried', async () => {
113 + const stalledBody = () =>
114 + new Response(
115 + new ReadableStream({
116 + start: controller => controller.enqueue(new TextEncoder().encode('{"ref":')),
117 + }),
118 + { status: 200 }
119 + );
120 + const github = scripted(stalledBody, () => json({ ref: 'refs/heads/next' }));
121 + expect(await call(github.fetcher, 'GET', { baseDelayMs: 1, timeout: '50 millis' })).toEqual({
122 + ref: 'refs/heads/next',
123 + });
124 + expect(github.seen).toHaveLength(2);
125 + });
126 +
127 + test('a response the schema cannot read is not retried', async () => {
128 + const github = scripted(() => json({ object: {} }));
129 + await expect(call(github.fetcher)).rejects.toThrow('cannot read');
130 + expect(github.seen).toHaveLength(1);
131 + });
132 +});
test/sdk-release-harness.ts
+39 -2
@@ -1,11 +1,13 @@
1 -import { Effect, FileSystem, Layer, Path } from 'effect';
1 +import { Duration, Effect, Fiber, FileSystem, Layer, Path } from 'effect';
2 import { FetchHttpClient } from 'effect/http';
3 +import { TestClock } from 'effect/testing';
4 import { GitHub } from '../scripts/sdk-release/github';
5 import { ReleaseServices, readFile } from '../scripts/sdk-release/runtime';
6
7 export type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
8
8 -const TestServices = Layer.provideMerge(GitHub.layer('token'), ReleaseServices);
9 +// Retries back off for a millisecond, so a test of a failing request does not wait seconds.
10 +const TestServices = Layer.provideMerge(GitHub.layer('token', { baseDelayMs: 1 }), ReleaseServices);
11 type TestServices = Layer.Success<typeof TestServices>;
12
13 /** Runs a release effect with Bun platform services, a test GitHub token, and an optional fake fetch. */
@@ -19,6 +21,41 @@ export const runRelease = <A, E>(
21 return Effect.runPromise(withFetch.pipe(Effect.provide(TestServices)));
22 };
23
24 +/** One real macrotask, so the fake fetch's promises settle between test-clock steps. */
25 +const settle = Effect.promise(() => new Promise<void>(resolve => setTimeout(resolve, 0)));
26 +
27 +/**
28 + * Runs a release effect on a test clock that moves `step` at a time until the effect ends, so a
29 + * registry wait of many minutes takes milliseconds. `fetch` reads the test clock through `now`, for
30 + * a registry that starts serving something at a given minute.
31 + */
32 +export const runOnTestClock = <A, E>(
33 + effect: Effect.Effect<A, E, TestServices>,
34 + fetch: (now: () => number) => Fetch,
35 + options: { readonly step?: Duration.Input; readonly limit?: Duration.Input } = {}
36 +): Promise<A> =>
37 + runRelease(
38 + Effect.gen(function* () {
39 + const clock = yield* TestClock.testClockWith(Effect.succeed);
40 + const now = () => clock.currentTimeMillisUnsafe();
41 + const fiber = yield* Effect.forkChild(
42 + effect.pipe(
43 + Effect.provideService(FetchHttpClient.Fetch, fetch(now) as typeof globalThis.fetch)
44 + )
45 + );
46 + const limit = Duration.toMillis(options.limit ?? '1 hour');
47 + while (fiber.pollUnsafe() === undefined && now() < limit) {
48 + yield* TestClock.adjust(options.step ?? '5 seconds');
49 + yield* settle;
50 + }
51 + if (fiber.pollUnsafe() === undefined) {
52 + yield* Fiber.interrupt(fiber);
53 + return yield* Effect.die(new Error(`Still running after ${limit / 60_000} test minutes`));
54 + }
55 + return yield* Fiber.join(fiber);
56 + }).pipe(Effect.provide(TestClock.layer()))
57 + );
58 +
59 export const json = (value: unknown, status = 200) =>
60 new Response(JSON.stringify(value), {
61 status,
test/sdk-release-npm-oidc.test.ts new
+134
@@ -0,0 +1,134 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { ConfigProvider, Console, Effect } from 'effect';
3 +import { NpmCli, publishNpm, type Distribution } from '../scripts/sdk-release/registry';
4 +import { CommandError, sha256Hex } from '../scripts/sdk-release/runtime';
5 +import { batch } from './sdk-release-controller-fixture';
6 +import { runRelease, type Fetch } from './sdk-release-harness';
7 +
8 +const ID_TOKEN_REQUEST_URL = 'https://token.actions.example.test/oidc?api-version=2.0';
9 +const ID_TOKEN_REQUEST_TOKEN = 'actions-request-secret';
10 +const ID_TOKEN = 'eyJhbGciOiJSUzI1NiJ9.eyJyZXBvc2l0b3J5IjoiQ29tcG9zaW9IUS9jb21wb3NpbyJ9.c2ln';
11 +const NPM_TOKEN = `npm_${'x'.repeat(36)}`;
12 +const EXCHANGE = 'https://registry.npmjs.org/-/npm/v1/oidc/token/exchange/package/';
13 +const REFUSAL = 'OIDC token exchange error - package not found';
14 +
15 +const tarball = async (name: string, file: string): Promise<Distribution> => {
16 + const bytes = new TextEncoder().encode(`original ${file}`);
17 + return {
18 + language: 'typescript',
19 + name,
20 + version: '1.0.1',
21 + file,
22 + bytes,
23 + sha256: await runRelease(sha256Hex(bytes)),
24 + };
25 +};
26 +const core = await tarball('@composio/core', 'composio-core-1.0.1.tgz');
27 +const openai = await tarball('@composio/openai', 'composio-openai-1.0.1.tgz');
28 +
29 +interface Sent {
30 + readonly method: string;
31 + readonly url: string;
32 + readonly authorization: string | null;
33 +}
34 +
35 +/** GitHub's ID-token endpoint, npm's exchange endpoint, and a registry that serves neither tarball yet. */
36 +const fakeRegistry = (refused: ReadonlySet<string>) => {
37 + const sent: Sent[] = [];
38 + const fetch: Fetch = async (input, init) => {
39 + const url = String(input);
40 + const method = init?.method ?? 'GET';
41 + sent.push({ method, url, authorization: new Headers(init?.headers).get('authorization') });
42 + if (url.startsWith('https://token.actions.example.test/'))
43 + return new Response(JSON.stringify({ value: ID_TOKEN }));
44 + if (url.startsWith(EXCHANGE))
45 + return refused.has(decodeURIComponent(url.slice(EXCHANGE.length)))
46 + ? new Response(JSON.stringify({ message: REFUSAL }), { status: 404 })
47 + : new Response(JSON.stringify({ token: NPM_TOKEN }));
48 + if (url.endsWith('/latest')) return new Response(JSON.stringify({ version: '1.0.0' }));
49 + if (url.startsWith('https://registry.npmjs.org/')) return new Response('{}', { status: 404 });
50 + throw new Error(`Unexpected request ${method} ${url}`);
51 + };
52 + return { sent, fetch };
53 +};
54 +
55 +const withActionsEnv = (env: Record<string, string>) =>
56 + Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown(env));
57 +
58 +const actionsEnv = {
59 + ACTIONS_ID_TOKEN_REQUEST_URL: ID_TOKEN_REQUEST_URL,
60 + ACTIONS_ID_TOKEN_REQUEST_TOKEN: ID_TOKEN_REQUEST_TOKEN,
61 +};
62 +
63 +/** Runs `publishNpm` against fakes and returns what it printed, the npm commands, and the failure. */
64 +const publish = async (files: Distribution[], fetch: Fetch, env: Record<string, string>) => {
65 + const printed: string[] = [];
66 + const commands: string[][] = [];
67 + const capture = (...args: ReadonlyArray<unknown>) => printed.push(args.map(String).join(' '));
68 + const console: Console.Console = Object.assign(Object.create(globalThis.console), {
69 + log: capture,
70 + info: capture,
71 + warn: capture,
72 + error: capture,
73 + });
74 + const failure = await runRelease(
75 + publishNpm('.', batch, files).pipe(
76 + withActionsEnv(env),
77 + Effect.provideService(NpmCli, {
78 + run: args => {
79 + commands.push([...args]);
80 + // Stops the run right after the first upload; later steps have their own tests.
81 + return Effect.fail(new CommandError({ message: 'stopped after publish', exitCode: 1 }));
82 + },
83 + }),
84 + Effect.provideService(Console.Console, console),
85 + Effect.flip
86 + ),
87 + fetch
88 + );
89 + const message = failure instanceof Error ? failure.message : String(failure);
90 + return { output: [...printed, message].join('\n'), message, commands };
91 +};
92 +
93 +const expectNoTokens = (output: string) => {
94 + expect(output).not.toContain('eyJ');
95 + expect(output).not.toContain('npm_');
96 + expect(output).not.toContain(ID_TOKEN_REQUEST_TOKEN);
97 +};
98 +
99 +describe('npm trusted-publishing login preflight', () => {
100 + test('a refused exchange for one package fails before any upload and names that package and npm’s reason', async () => {
101 + const registry = fakeRegistry(new Set(['@composio/openai']));
102 + const result = await publish([core, openai], registry.fetch, actionsEnv);
103 + expect(result.commands).toEqual([]);
104 + expect(result.message).toContain(`@composio/openai (404): ${REFUSAL}`);
105 + expect(result.message).not.toContain('@composio/core (');
106 + expect(result.output).toContain('@composio/core');
107 + expectNoTokens(result.output);
108 + });
109 +
110 + test('accepted exchanges let publishing proceed without printing either token', async () => {
111 + const registry = fakeRegistry(new Set());
112 + const result = await publish([core, openai], registry.fetch, actionsEnv);
113 + expect(result.commands[0]?.slice(0, 1)).toEqual(['publish']);
114 + expect(result.message).toContain('stopped after publish');
115 + expectNoTokens(result.output);
116 + expect(registry.sent.slice(0, 3)).toEqual([
117 + {
118 + method: 'GET',
119 + url: `${ID_TOKEN_REQUEST_URL}&audience=npm%3Aregistry.npmjs.org`,
120 + authorization: `Bearer ${ID_TOKEN_REQUEST_TOKEN}`,
121 + },
122 + { method: 'POST', url: `${EXCHANGE}@composio%2fcore`, authorization: `Bearer ${ID_TOKEN}` },
123 + { method: 'POST', url: `${EXCHANGE}@composio%2fopenai`, authorization: `Bearer ${ID_TOKEN}` },
124 + ]);
125 + });
126 +
127 + test('without the GitHub ID-token request env the preflight names the missing id-token permission', async () => {
128 + const registry = fakeRegistry(new Set());
129 + const result = await publish([core], registry.fetch, {});
130 + expect(result.message).toContain('id-token permission missing');
131 + expect(result.commands).toEqual([]);
132 + expect(registry.sent).toEqual([]);
133 + });
134 +});
test/sdk-release-provenance.test.ts
+50 -19
@@ -1,7 +1,7 @@
1 import { describe, expect, test } from 'bun:test';
2 import { verifyPypiProvenance } from '../scripts/sdk-release/provenance';
3 import { verifyPypiFiles, type Distribution } from '../scripts/sdk-release/registry';
4 -import { runRelease, type Fetch } from './sdk-release-harness';
4 +import { runOnTestClock, type Fetch } from './sdk-release-harness';
5
6 const wheel: Distribution = {
7 language: 'python',
@@ -18,27 +18,58 @@ const releasePublisher = {
18 workflow: 'sdk.release.yml',
19 environment: 'pypi-release',
20 };
21 -const noWait = { attempts: 2, spacing: '0 millis' } as const;
21
23 -/** PyPI's integrity and version metadata endpoints for one wheel, with `publisher` attesting it. */
22 +/**
23 + * PyPI's integrity and version metadata endpoints for one wheel, with `publisher` attesting it.
24 + * The provenance endpoint first answers each of `before`, then serves the attestation.
25 + */
26 const pypi =
25 - (publisher: Record<string, string> | undefined): Fetch =>
26 - async input => {
27 - const url = String(input);
28 - if (url === `https://pypi.org/integrity/composio/0.31.1b8/${wheel.file}/provenance`)
29 - return publisher
30 - ? Response.json({ version: 1, attestation_bundles: [{ publisher, attestations: [] }] })
31 - : new Response('{}', { status: 404 });
32 - if (url === 'https://pypi.org/pypi/composio/0.31.1b8/json')
33 - return Response.json({
34 - urls: [{ filename: wheel.file, url: fileUrl, digests: { sha256: '' } }],
35 - });
36 - throw new Error(`Unexpected PyPI request: ${url}`);
27 + (publisher: Record<string, string> | undefined, before: ReadonlyArray<number> = []) =>
28 + (): Fetch => {
29 + const pending = [...before];
30 + return async input => {
31 + const url = String(input);
32 + if (url === `https://pypi.org/integrity/composio/0.31.1b8/${wheel.file}/provenance`) {
33 + const status = pending.shift();
34 + if (status !== undefined) return new Response('{}', { status });
35 + return publisher
36 + ? Response.json({ version: 1, attestation_bundles: [{ publisher, attestations: [] }] })
37 + : new Response('{}', { status: 404 });
38 + }
39 + if (url === 'https://pypi.org/pypi/composio/0.31.1b8/json')
40 + return Response.json({
41 + urls: [{ filename: wheel.file, url: fileUrl, digests: { sha256: '' } }],
42 + });
43 + throw new Error(`Unexpected PyPI request: ${url}`);
44 + };
45 };
46
47 describe('PyPI attestations', () => {
48 test('a file attested by the release workflow in pypi-release is accepted', async () => {
41 - await runRelease(verifyPypiProvenance(wheel, noWait), pypi(releasePublisher));
49 + await runOnTestClock(verifyPypiProvenance(wheel), pypi(releasePublisher));
50 + });
51 +
52 + test.each([
53 + ['404 for 10 polls', Array.from({ length: 10 }, () => 404)],
54 + ['429', [429]],
55 + ])('provenance that answers %s and is then present is accepted', async (_name, before) => {
56 + await runOnTestClock(verifyPypiProvenance(wheel), pypi(releasePublisher, before));
57 + });
58 +
59 + test('a provenance lookup that stalls is retried, then accepted', async () => {
60 + let stalled = false;
61 + const stallOnce = (): Fetch => {
62 + const served = pypi(releasePublisher)();
63 + return async (input, init) => {
64 + if (!stalled && String(input).endsWith('/provenance')) {
65 + stalled = true;
66 + return new Promise<Response>(() => {});
67 + }
68 + return served(input, init);
69 + };
70 + };
71 + await runOnTestClock(verifyPypiProvenance(wheel), stallOnce);
72 + expect(stalled).toBe(true);
73 });
74
75 test.each([
@@ -47,18 +78,18 @@ describe('PyPI attestations', () => {
78 ['another environment', { environment: 'pypi' }],
79 ])('a file attested by %s is refused', async (_name, change) => {
80 await expect(
50 - runRelease(verifyPypiProvenance(wheel, noWait), pypi({ ...releasePublisher, ...change }))
81 + runOnTestClock(verifyPypiProvenance(wheel), pypi({ ...releasePublisher, ...change }))
82 ).rejects.toThrow('is not attested by ComposioHQ/composio sdk.release.yml in pypi-release');
83 });
84
85 test('a file without provenance is refused once the wait runs out', async () => {
55 - await expect(runRelease(verifyPypiProvenance(wheel, noWait), pypi(undefined))).rejects.toThrow(
86 + await expect(runOnTestClock(verifyPypiProvenance(wheel), pypi(undefined))).rejects.toThrow(
87 'No provenance is published at https://pypi.org/integrity/composio'
88 );
89 });
90
91 test('verified files return the URLs PyPI serves, for the signature check', async () => {
61 - expect(await runRelease(verifyPypiFiles([wheel], noWait), pypi(releasePublisher))).toEqual([
92 + expect(await runOnTestClock(verifyPypiFiles([wheel]), pypi(releasePublisher))).toEqual([
93 fileUrl,
94 ]);
95 });
test/sdk-release-publication.test.ts
+106 -19
@@ -1,16 +1,19 @@
1 import { describe, expect, test } from 'bun:test';
2 +import { Effect } from 'effect';
3 import type { Channel } from '../scripts/sdk-release/channel';
4 import type { Language } from '../scripts/sdk-release/lanes';
5 import {
6 + NpmCli,
7 loadOriginalDistributions,
8 + npmDistTag,
9 reconcileRegistry as reconcileRegistryEffect,
10 waitForRegistry,
11 type Distribution,
12 } from '../scripts/sdk-release/registry';
13 import { docsPinSpecs } from '../scripts/sdk-release/report';
11 -import { sha256Hex } from '../scripts/sdk-release/runtime';
14 +import { CommandError, sha256Hex } from '../scripts/sdk-release/runtime';
15 import { batch, head } from './sdk-release-controller-fixture';
13 -import { runRelease, type Fetch } from './sdk-release-harness';
16 +import { runOnTestClock, runRelease, type Fetch } from './sdk-release-harness';
17
18 const distribution = async (file: string, language: Language = 'python'): Promise<Distribution> => {
19 const bytes = new TextEncoder().encode(`original ${file}`);
@@ -125,16 +128,6 @@ describe('registry reconciliation', () => {
128 const result = await reconcileRegistry([tarball], registry([tarball], { newer: true }).fetcher);
129 expect(result.tagsToRepair).toEqual([]);
130 });
128 - test('bounded propagation ends with the exact incomplete file inventory', async () => {
129 - const fake = registry([wheel]);
130 - await expect(
131 - runRelease(
132 - waitForRegistry([wheel, sdist], { attempts: 3, spacing: '0 millis' }),
133 - fake.fetcher
134 - )
135 - ).rejects.toThrow(`after 3 attempts: composio@1.0.1/${sdist.file}`);
136 - expect(fake.reads.filter(url => url.startsWith('https://pypi.org/'))).toHaveLength(3);
137 - });
131 test('a fresh npm upload is polled until visible, then its channel tag is left to move', async () => {
132 const fake = registry([tarball]);
133 let lookups = 0;
@@ -145,9 +138,9 @@ describe('registry reconciliation', () => {
138 return new Response('{}', { status: 404 });
139 return fake.fetcher(input);
140 };
148 - const state = await runRelease(
149 - waitForRegistry([tarball], { attempts: 3, spacing: '0 millis', channelTags: false }),
150 - lagging
141 + const state = await runOnTestClock(
142 + waitForRegistry([tarball], { channelTags: false }),
143 + () => lagging
144 );
145 expect(state.missing).toEqual([]);
146 expect(state.tagsToRepair).toEqual([
@@ -172,10 +165,7 @@ describe('registry reconciliation', () => {
165 test('a content conflict fails at once instead of waiting for propagation', async () => {
166 const fake = registry([wheel], { conflict: true });
167 await expect(
175 - runRelease(
176 - waitForRegistry([wheel, sdist], { attempts: 3, spacing: '0 millis' }),
177 - fake.fetcher
178 - )
168 + runOnTestClock(waitForRegistry([wheel, sdist]), () => fake.fetcher)
169 ).rejects.toThrow(`Registry content conflict: composio@1.0.1/${wheel.file}`);
170 expect(fake.reads.filter(url => url.startsWith('https://pypi.org/'))).toHaveLength(1);
171 });
@@ -194,6 +184,77 @@ describe('registry reconciliation', () => {
184 });
185 });
186
187 +describe('waiting out npm’s publish-time scan', () => {
188 + const MINUTE = 60_000;
189 + const openai = { ...tarball, name: '@composio/openai', file: 'composio-openai-1.0.1.tgz' };
190 + const versionUrl = 'https://registry.npmjs.org/%40composio%2Fcore/1.0.1';
191 +
192 + /** npm answers 404 for each version until `served` says it has finished scanning. */
193 + const scanning = (served: (reads: number, now: number) => boolean) => {
194 + const reads: string[] = [];
195 + let clock = () => 0;
196 + const fake = registry([tarball]);
197 + const fetch = (now: () => number): Fetch => {
198 + clock = now;
199 + return async input => {
200 + const url = String(input);
201 + if (url.endsWith('/latest')) return new Response(JSON.stringify({ version: '1.0.0' }));
202 + if (url.startsWith('https://registry.npmjs.org/%40')) {
203 + reads.push(url);
204 + if (!served(reads.filter(read => read === url).length - 1, now()))
205 + return new Response('{}', { status: 404 });
206 + }
207 + return fake.fetcher(input);
208 + };
209 + };
210 + return { reads, fetch, elapsed: () => clock() };
211 + };
212 +
213 + test('a version npm serves after 8 polls of 404 is accepted within the deadline', async () => {
214 + const npm = scanning(reads => reads >= 8);
215 + const state = await runOnTestClock(
216 + waitForRegistry([tarball], { channelTags: false }),
217 + npm.fetch
218 + );
219 + expect(state.missing).toEqual([]);
220 + expect(npm.reads.filter(url => url === versionUrl)).toHaveLength(9);
221 + expect(npm.elapsed()).toBeLessThan(20 * MINUTE);
222 + });
223 +
224 + test('a 15-minute scan is waited out', async () => {
225 + const npm = scanning((_reads, now) => now >= 15 * MINUTE);
226 + const state = await runOnTestClock(
227 + waitForRegistry([tarball], { channelTags: false }),
228 + npm.fetch
229 + );
230 + expect(state.missing).toEqual([]);
231 + expect(npm.elapsed()).toBeGreaterThanOrEqual(15 * MINUTE);
232 + });
233 +
234 + test('a registry error that waiting cannot fix fails at once', async () => {
235 + const npm = scanning(() => false);
236 + const unauthorized =
237 + (now: () => number): Fetch =>
238 + async input =>
239 + String(input) === versionUrl ? new Response('{}', { status: 401 }) : npm.fetch(now)(input);
240 + await expect(
241 + runOnTestClock(waitForRegistry([tarball], { channelTags: false }), unauthorized)
242 + ).rejects.toThrow(`Registry lookup failed: ${versionUrl} (401)`);
243 + expect(npm.elapsed()).toBeLessThan(MINUTE);
244 + });
245 +
246 + test('versions still missing at the 20-minute deadline fail naming each one', async () => {
247 + const npm = scanning(() => false);
248 + await expect(
249 + runOnTestClock(waitForRegistry([tarball, openai], { channelTags: false }), npm.fetch)
250 + ).rejects.toThrow(
251 + `when the registry wait (20 minutes) ended: @composio/core@1.0.1/${tarball.file}, @composio/openai@1.0.1/${openai.file}`
252 + );
253 + expect(npm.elapsed()).toBeGreaterThanOrEqual(20 * MINUTE);
254 + expect(npm.elapsed()).toBeLessThan(22 * MINUTE);
255 + });
256 +});
257 +
258 describe('pinned candidate download', () => {
259 const pinned = { run: 41, artifactId: 77, digest: `sha256:${'c'.repeat(64)}` };
260 const listed = (overrides: { digest?: string; run?: number }) => ({
@@ -234,6 +295,32 @@ describe('pinned candidate download', () => {
295 });
296 });
297
298 +describe('npm dist-tag moves', () => {
299 + // The E403 npm printed when the trusted publisher of @composio/slim lacked the dist-tag permission.
300 + const refusal = [
301 + 'npm failed: npm error code E403',
302 + 'npm error 403 403 Forbidden - PUT https://registry.npmjs.org/-/package/@composio%2fslim/dist-tags/latest - This trusted publisher cannot manage dist-tags. Ask a package maintainer to enable Allow npm dist-tag.',
303 + ].join('\n');
304 + test('a dist-tag refusal names the trusted-publisher setting to enable', async () => {
305 + const commands: string[][] = [];
306 + await expect(
307 + runRelease(
308 + npmDistTag(['add', '@composio/slim@1.0.1', 'latest'], '@composio/slim').pipe(
309 + Effect.provideService(NpmCli, {
310 + run: args => {
311 + commands.push([...args]);
312 + return Effect.fail(new CommandError({ message: refusal, exitCode: 1 }));
313 + },
314 + })
315 + )
316 + )
317 + ).rejects.toThrow(
318 + /@composio\/slim.*Allow npm dist-tag.*Settings → Trusted publishing.*ts\/docs\/internal\/release\.md#npm-trusted-publishing/s
319 + );
320 + expect(commands).toEqual([['dist-tag', 'add', '@composio/slim@1.0.1', 'latest']]);
321 + });
322 +});
323 +
324 test('docs pins move only used packages forward, so an older retry never downgrades them', () => {
325 expect(
326 docsPinSpecs(
test/sdk-release-regate.test.ts new
+99
@@ -0,0 +1,99 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { Effect, Exit } from 'effect';
3 +import { regateRelease, releaseToRegate } from '../scripts/sdk-release/batch';
4 +import {
5 + APP_SLUG,
6 + fakeController,
7 + head,
8 + merge,
9 + type ControllerOptions,
10 +} from './sdk-release-controller-fixture';
11 +import { json, readText, runRelease } from './sdk-release-harness';
12 +
13 +/** Regate as the workflow runs it: `next` at batch 8's merge commit, dispatched by the requester. */
14 +const regate = (fetcher: ReturnType<typeof fakeController>['fetcher'], actor = 'requester') =>
15 + runRelease(
16 + Effect.exit(
17 + Effect.flatMap(releaseToRegate(actor, merge), ({ pull, batch }) =>
18 + regateRelease(pull, batch, APP_SLUG)
19 + )
20 + ),
21 + fetcher
22 + );
23 +
24 +const pull = 'https://github.com/ComposioHQ/composio/pull/9';
25 +const tagged = Exit.succeed({ _tag: 'Tagged', tag: 'sdk-release/8' } as const);
26 +const controller = (options: ControllerOptions = {}) => fakeController(options);
27 +
28 +describe('regate', () => {
29 + test('tags the merged, untagged release on next at its reviewed head', async () => {
30 + const github = controller();
31 + expect(await regate(github.fetcher)).toEqual(tagged);
32 + expect(github.writes).toEqual([
33 + { method: 'POST', path: '/git/refs', body: { ref: 'refs/tags/sdk-release/8', sha: head } },
34 + ]);
35 + });
36 +
37 + test('reports Tagged without writing when the tag is already on the reviewed head', async () => {
38 + const github = controller({ existingTag: head });
39 + expect(await regate(github.fetcher)).toEqual(tagged);
40 + expect(github.writes).toEqual([]);
41 + });
42 +
43 + test("leaves an already-tagged release alone, even one today's gate would refuse", async () => {
44 + const github = controller({ existingTag: head, docs: 'missing' });
45 + expect(await regate(github.fetcher)).toEqual(tagged);
46 + expect(github.writes).toEqual([]);
47 + });
48 +
49 + test('refuses a tag that points at another commit', async () => {
50 + const github = controller({ existingTag: merge });
51 + expect(String(await regate(github.fetcher))).toContain('already points to another source');
52 + expect(github.writes).toEqual([]);
53 + });
54 +
55 + test('fails with nothing to re-gate when next carries no release plan', async () => {
56 + const github = controller({ noPlanOnNext: true });
57 + expect(String(await regate(github.fetcher))).toContain('Nothing to re-gate');
58 + expect(github.writes).toEqual([]);
59 + });
60 +
61 + test('reports a release PR closed without merging as abandoned', async () => {
62 + const github = controller({ closedUnmerged: true });
63 + expect(await regate(github.fetcher)).toEqual(Exit.succeed({ _tag: 'Abandoned', pull }));
64 + expect(github.writes).toEqual([]);
65 + });
66 +
67 + test('refuses a release that fails the gate, exactly as the tag job does', async () => {
68 + const github = controller({ oldReview: true });
69 + expect(await regate(github.fetcher)).toEqual(
70 + Exit.succeed({ _tag: 'Refused', pull, reason: expect.stringContaining('lacks an approval') })
71 + );
72 + expect(github.writes.map(write => write.path)).toEqual(['/issues/9/comments']);
73 + });
74 +
75 + test('requires an active ComposioHQ member', async () => {
76 + const github = controller();
77 + const outsider: typeof github.fetcher = (input, init) =>
78 + new URL(String(input)).pathname === '/orgs/ComposioHQ/memberships/outsider'
79 + ? Promise.resolve(json({ message: 'Not Found' }, 404))
80 + : github.fetcher(input, init);
81 + expect(String(await regate(outsider, 'outsider'))).toContain('(404)');
82 + expect(github.writes).toEqual([]);
83 + });
84 +});
85 +
86 +describe('regate job', () => {
87 + test('runs only for a regate dispatch on next, in the tag job concurrency group', async () => {
88 + const workflow = Bun.YAML.parse(await readText('.github/workflows/sdk.release.yml')) as {
89 + on: { workflow_dispatch: { inputs: { action: { options: string[] } } } };
90 + jobs: Record<string, { if?: string; concurrency?: { group: string } }>;
91 + };
92 + expect(workflow.on.workflow_dispatch.inputs.action.options).toEqual(['request', 'regate']);
93 + const { regate, tag, plan } = workflow.jobs;
94 + expect(regate.if).toContain("github.ref == 'refs/heads/next'");
95 + expect(regate.if).toContain("inputs.action == 'regate'");
96 + expect(plan.if).toContain("inputs.action == 'request'");
97 + expect(regate.concurrency?.group).toBe(tag.concurrency?.group);
98 + });
99 +});
test/sdk-release-rehearsal.test.ts
+158 -68
@@ -1,5 +1,5 @@
1 import { describe, expect, test } from 'bun:test';
2 -import { Effect, Layer, Option } from 'effect';
2 +import { ConfigProvider, Effect, Layer, Option } from 'effect';
3 import { Digest } from 'effect/crypto';
4 import { Base64 } from 'effect/encoding';
5 import semver from 'semver';
@@ -11,7 +11,7 @@ import {
11 } from '../scripts/sdk-release/batch';
12 import { NpmCli, publishNpm, type Distribution } from '../scripts/sdk-release/registry';
13 import { stageOutcome } from '../scripts/sdk-release/report';
14 -import { sha256Hex } from '../scripts/sdk-release/runtime';
14 +import { CommandError, sha256Hex } from '../scripts/sdk-release/runtime';
15 import type { ReleaseBatch } from '../scripts/sdk-release/source';
16 import { STAGES, type ReleaseState, type StateName } from '../scripts/sdk-release/state';
17 import {
@@ -23,22 +23,28 @@ import {
23 head,
24 releaseFiles,
25 } from './sdk-release-controller-fixture';
26 -import { resolvePath, runRelease, type Fetch } from './sdk-release-harness';
26 +import { resolvePath, runOnTestClock, runRelease, type Fetch } from './sdk-release-harness';
27
28 const NPM = 'https://registry.npmjs.org';
29 +const MINUTE = 60_000;
30 +const ID_TOKEN_REQUEST_URL = 'https://token.actions.example.test/oidc?api-version=2.0';
31
32 /**
33 * A fake npm registry with its dist-tags, and the npm CLI that writes to it. Uploads record SLSA
34 * provenance the way trusted publishing does, from `ref` (the release tag unless a test forges
33 - * another one).
35 + * another one). The trusted-publishing login succeeds. With `uploaded`, an earlier run already
36 + * uploaded those bytes for the staged version, so npm refuses another upload of it; npm hides
37 + * every version and its provenance until the test clock reaches `scanUntil`.
38 */
39 function npmRegistry(
40 tags: Record<string, string>,
37 - options: { ref?: string; otherBytes?: boolean } = {}
41 + options: { ref?: string; otherBytes?: boolean; uploaded?: Uint8Array; scanUntil?: number } = {}
42 ) {
43 const versions = new Map<string, Uint8Array>();
44 const commands: string[] = [];
45 const pending = new Map<string, Distribution>();
46 + let uploads = 0;
47 + let clock = () => 0;
48 const sha512 = (bytes: Uint8Array) =>
49 runRelease(
50 Effect.gen(function* () {
@@ -46,7 +52,36 @@ function npmRegistry(
52 })
53 );
54 const provenance = new Map<string, string>();
49 - const cli = Layer.succeed(NpmCli, {
55 + const actionsEnv = ConfigProvider.layer(
56 + ConfigProvider.fromUnknown({
57 + ACTIONS_ID_TOKEN_REQUEST_URL: ID_TOKEN_REQUEST_URL,
58 + ACTIONS_ID_TOKEN_REQUEST_TOKEN: 'request-token',
59 + })
60 + );
61 + /** Stores `bytes` as `version` under the release-only tag, with provenance for those bytes. */
62 + const record = async (version: string, bytes: Uint8Array, releaseOnly: string) => {
63 + versions.set(version, bytes);
64 + tags[releaseOnly] = version;
65 + const statement = {
66 + subject: [
67 + { digest: { sha512: await sha512(options.otherBytes ? new Uint8Array([1]) : bytes) } },
68 + ],
69 + predicate: {
70 + buildDefinition: {
71 + externalParameters: {
72 + workflow: {
73 + ref:
74 + options.ref ?? `refs/tags/sdk-release/${releaseOnly.slice('sdk-release-'.length)}`,
75 + repository: 'https://github.com/ComposioHQ/composio',
76 + path: '.github/workflows/sdk.release.yml',
77 + },
78 + },
79 + },
80 + },
81 + };
82 + provenance.set(version, Base64.encode(JSON.stringify(statement)));
83 + };
84 + const npmCli = Layer.succeed(NpmCli, {
85 run: (args: ReadonlyArray<string>) =>
86 Effect.promise(async () => {
87 commands.push(args.join(' '));
@@ -54,71 +89,87 @@ function npmRegistry(
89 if (command === 'publish') {
90 const file = [...pending.values()].find(candidate => target.endsWith(candidate.file));
91 if (!file) throw new Error(`Unexpected upload ${target}`);
57 - versions.set(file.version, file.bytes);
58 - const releaseOnly = args.find(arg => arg.startsWith('--tag='))!.slice('--tag='.length);
59 - tags[releaseOnly] = file.version;
60 - const statement = {
61 - subject: [
62 - {
63 - digest: {
64 - sha512: await sha512(options.otherBytes ? new Uint8Array([1]) : file.bytes),
65 - },
66 - },
67 - ],
68 - predicate: {
69 - buildDefinition: {
70 - externalParameters: {
71 - workflow: {
72 - ref:
73 - options.ref ??
74 - `refs/tags/sdk-release/${releaseOnly.slice('sdk-release-'.length)}`,
75 - repository: 'https://github.com/ComposioHQ/composio',
76 - path: '.github/workflows/sdk.release.yml',
77 - },
78 - },
79 - },
80 - },
81 - };
82 - provenance.set(file.version, Base64.encode(JSON.stringify(statement)));
92 + // npm 11.21.0 refuses a version the registry already holds, scanned or not.
93 + if (versions.has(file.version))
94 + return new CommandError({
95 + message: [
96 + 'npm failed: npm error code E403',
97 + `npm error 403 403 Forbidden - PUT ${NPM}/@composio%2fcore - You cannot publish over the previously published versions: ${file.version}.`,
98 + ].join('\n'),
99 + exitCode: 1,
100 + });
101 + uploads++;
102 + await record(
103 + file.version,
104 + file.bytes,
105 + args.find(arg => arg.startsWith('--tag='))!.slice('--tag='.length)
106 + );
107 }
108 if (command === 'dist-tag' && target === 'add') tags[args[3]] = args[2].split('@').at(-1)!;
109 if (command === 'dist-tag' && target === 'rm') delete tags[args[3]];
110 return '';
87 - }),
111 + }).pipe(
112 + Effect.flatMap(result =>
113 + typeof result === 'string' ? Effect.succeed(result) : Effect.fail(result)
114 + )
115 + ),
116 });
89 - const fetcher: Fetch = async input => {
90 - const url = String(input);
91 - const respond = (data: unknown) => new Response(JSON.stringify(data));
92 - const notFound = new Response('{}', { status: 404 });
93 - if (url === `${NPM}/-/package/%40composio%2Fcore/dist-tags`) return respond(tags);
94 - const attestation = /\/-\/npm\/v1\/attestations\/%40composio%2Fcore@(.+)$/.exec(url);
95 - if (attestation)
96 - return provenance.has(attestation[1])
97 - ? respond({
98 - attestations: [
99 - {
100 - predicateType: 'https://slsa.dev/provenance/v1',
101 - bundle: { dsseEnvelope: { payload: provenance.get(attestation[1]) } },
102 - },
103 - ],
104 - })
105 - : notFound;
106 - const tarball = /\/@composio\/core\/-\/core-(.+)\.tgz$/.exec(url);
107 - if (tarball) return new Response((versions.get(tarball[1]) ?? new Uint8Array()).slice());
108 - const document = /^https:\/\/registry\.npmjs\.org\/%40composio%2Fcore\/(.+)$/.exec(url);
109 - if (document && semver.valid(document[1]))
110 - return versions.has(document[1])
111 - ? respond({
112 - name: '@composio/core',
113 - version: document[1],
114 - dist: { tarball: `${NPM}/@composio/core/-/core-${document[1]}.tgz` },
115 - })
116 - : notFound;
117 - if (document) return document[1] in tags ? respond({ version: tags[document[1]] }) : notFound;
118 - throw new Error(`Unexpected registry request: ${url}`);
117 + const cli = Layer.mergeAll(npmCli, actionsEnv);
118 + const fetchAt =
119 + (now: () => number): Fetch =>
120 + async input => {
121 + clock = now;
122 + const url = String(input);
123 + const respond = (data: unknown) => new Response(JSON.stringify(data));
124 + const notFound = new Response('{}', { status: 404 });
125 + const scanned = (version: string) =>
126 + versions.has(version) && now() >= (options.scanUntil ?? 0);
127 + if (url.startsWith(ID_TOKEN_REQUEST_URL)) return respond({ value: 'id-token' });
128 + if (url === `${NPM}/-/npm/v1/oidc/token/exchange/package/@composio%2fcore`)
129 + return respond({ token: 'exchanged-token' });
130 + if (url === `${NPM}/-/package/%40composio%2Fcore/dist-tags`) return respond(tags);
131 + const attestation = /\/-\/npm\/v1\/attestations\/%40composio%2Fcore@(.+)$/.exec(url);
132 + if (attestation)
133 + return scanned(attestation[1])
134 + ? respond({
135 + attestations: [
136 + {
137 + predicateType: 'https://slsa.dev/provenance/v1',
138 + bundle: { dsseEnvelope: { payload: provenance.get(attestation[1]) } },
139 + },
140 + ],
141 + })
142 + : notFound;
143 + const tarball = /\/@composio\/core\/-\/core-(.+)\.tgz$/.exec(url);
144 + if (tarball) return new Response((versions.get(tarball[1]) ?? new Uint8Array()).slice());
145 + const document = /^https:\/\/registry\.npmjs\.org\/%40composio%2Fcore\/(.+)$/.exec(url);
146 + if (document && semver.valid(document[1]))
147 + return scanned(document[1])
148 + ? respond({
149 + name: '@composio/core',
150 + version: document[1],
151 + dist: { tarball: `${NPM}/@composio/core/-/core-${document[1]}.tgz` },
152 + })
153 + : notFound;
154 + if (document) return document[1] in tags ? respond({ version: tags[document[1]] }) : notFound;
155 + throw new Error(`Unexpected registry request: ${url}`);
156 + };
157 + const fetcher = fetchAt(() => 0);
158 + const stage = async (file: Distribution) => {
159 + pending.set(file.file, file);
160 + // The earlier run was batch 8's, so its release-only tag is still in place.
161 + if (options.uploaded) await record(file.version, options.uploaded, 'sdk-release-8');
162 + };
163 + return {
164 + cli,
165 + fetcher,
166 + fetchAt,
167 + commands,
168 + tags,
169 + stage,
170 + uploads: () => uploads,
171 + elapsed: () => clock(),
172 };
120 - const stage = (file: Distribution) => pending.set(file.file, file);
121 - return { cli, fetcher, commands, tags, stage };
173 }
174
175 const tarballOf = async (release: ReleaseBatch): Promise<Distribution> => {
@@ -189,7 +240,7 @@ async function rehearse(release: ReleaseBatch, tags: Record<string, string>) {
240 // 3. publish: the reviewed tarball reaches npm, and a re-run uploads nothing.
241 const registry = npmRegistry(tags);
242 const tarball = await tarballOf(release);
192 - registry.stage(tarball);
243 + await registry.stage(tarball);
244 const publish = publishNpm(cwd, release, [tarball]).pipe(Effect.provide(registry.cli));
245 await runRelease(publish, registry.fetcher);
246 const firstRun = [...registry.commands];
@@ -234,7 +285,7 @@ describe('release rehearsal', () => {
285 test('provenance from another ref fails the publication before latest moves', async () => {
286 const registry = npmRegistry({ latest: '1.0.0' }, { ref: 'refs/heads/next' });
287 const tarball = await tarballOf(batch);
237 - registry.stage(tarball);
288 + await registry.stage(tarball);
289 await expect(
290 runRelease(
291 publishNpm(await resolvePath('.'), batch, [tarball]).pipe(Effect.provide(registry.cli)),
@@ -248,7 +299,7 @@ describe('release rehearsal', () => {
299 test('provenance that describes other bytes fails the publication', async () => {
300 const registry = npmRegistry({ latest: '1.0.0' }, { otherBytes: true });
301 const tarball = await tarballOf(batch);
251 - registry.stage(tarball);
302 + await registry.stage(tarball);
303 await expect(
304 runRelease(
305 publishNpm(await resolvePath('.'), batch, [tarball]).pipe(Effect.provide(registry.cli)),
@@ -257,6 +308,45 @@ describe('release rehearsal', () => {
308 ).rejects.toThrow('provenance describes other bytes than the reviewed tarball');
309 });
310
311 + test('a re-run during npm’s 15-minute scan waits it out and moves latest without a second upload', async () => {
312 + const tarball = await tarballOf(batch);
313 + const registry = npmRegistry(
314 + { latest: '1.0.0' },
315 + { uploaded: tarball.bytes, scanUntil: 15 * MINUTE }
316 + );
317 + await registry.stage(tarball);
318 + await runOnTestClock(
319 + publishNpm(await resolvePath('.'), batch, [tarball]).pipe(Effect.provide(registry.cli)),
320 + registry.fetchAt
321 + );
322 + expect(registry.uploads()).toBe(0);
323 + expect(registry.commands).toEqual([
324 + `publish ${await resolvePath('sdk-publication/typescript/composio-core-1.0.1.tgz')} --ignore-scripts --provenance --access=public --tag=sdk-release-8`,
325 + 'dist-tag add @composio/core@1.0.1 latest',
326 + 'dist-tag rm @composio/core sdk-release-8',
327 + ]);
328 + expect(registry.tags).toEqual({ latest: '1.0.1' });
329 + expect(registry.elapsed()).toBeGreaterThanOrEqual(15 * MINUTE);
330 + });
331 +
332 + test('a re-run whose earlier upload differs from the reviewed tarball fails once npm serves it', async () => {
333 + const tarball = await tarballOf(batch);
334 + const registry = npmRegistry(
335 + { latest: '1.0.0' },
336 + { uploaded: new TextEncoder().encode('other tarball'), scanUntil: MINUTE }
337 + );
338 + await registry.stage(tarball);
339 + await expect(
340 + runOnTestClock(
341 + publishNpm(await resolvePath('.'), batch, [tarball]).pipe(Effect.provide(registry.cli)),
342 + registry.fetchAt
343 + )
344 + ).rejects.toThrow(`Registry content conflict: @composio/core@1.0.1/${tarball.file}`);
345 + expect(registry.elapsed()).toBeLessThan(3 * MINUTE);
346 + expect(registry.tags.latest).toBe('1.0.0');
347 + expect(registry.commands.some(command => command.startsWith('dist-tag'))).toBe(false);
348 + });
349 +
350 test('every state a stage can end in is reached by a production handler', async () => {
351 const reached = new Set<StateName>();
352 for (const { ended } of [
test/sdk-release-request.test.ts
-2
@@ -52,8 +52,6 @@ const openRelease = {
52 number: 9,
53 html_url: 'https://github.com/ComposioHQ/composio/pull/9',
54 state: 'open',
55 - merged: false,
56 - merge_commit_sha: null,
55 user: { login: 'sdk-release-app[bot]' },
56 head: { sha, ref: 'sdk-release/batch-8', repo: { full_name: 'ComposioHQ/composio' } },
57 base: { ref: 'next' },
test/sdk-release-state.test.ts
+13
@@ -160,6 +160,7 @@ function requestIssue(comments: { id: number; login: string; body: string }[] =
160 for (const label of body.labels) labels.add(label);
161 return respond([]);
162 }
163 + if (method === 'GET' && path === '/issues/8') return respond({ state });
164 if (method === 'PATCH' && path === '/issues/8') {
165 state = body.state;
166 return respond({});
@@ -194,6 +195,18 @@ describe('status on the request issue', () => {
195 expect(issue.writes).toContain('POST /issues/8/comments');
196 });
197
198 + test('a release tagged after it was refused reopens its request issue', async () => {
199 + const issue = requestIssue();
200 + await runRelease(showStatus(8, EXAMPLES.Refused, run, 'review'), issue.fetcher);
201 + expect(issue.state()).toBe('closed');
202 + await runRelease(showStatus(8, EXAMPLES.Tagged, run, 'review'), issue.fetcher);
203 + expect(issue.state()).toBe('open');
204 + expect(issue.comments).toEqual([
205 + expect.objectContaining({ body: expect.stringContaining('Tagged `sdk-release/8`') }),
206 + ]);
207 + expect([...issue.labels]).toEqual(['SDK release', 'sdk-release:publishing']);
208 + });
209 +
210 test('a late or re-run earlier stage never replaces a later stage result', async () => {
211 const issue = requestIssue();
212 await runRelease(showStatus(8, EXAMPLES.Published, run, 'publish'), issue.fetcher);
ts/docs/internal/release.md
+48 -23
@@ -11,18 +11,18 @@ request (issue or dispatch) → release PR (bot) → candidate checks → approv
11
12 The request issue always shows where the release is: one status comment that the bot edits in place, and one `sdk-release:<state>` label. `scripts/sdk-release/state.ts` lists every state and which stage can end in it.
13
14 -| State | Meaning | Issue |
15 -| ------------- | ----------------------------------------------------------------------------------------------- | ------ |
16 -| `in-review` | The release PR is open. | open |
17 -| `publishing` | The merged PR is tagged; the tag run is publishing. | open |
18 -| `published` | Every planned package is on its registry. | closed |
19 -| `failed` | A job failed or was cancelled. **Re-run failed jobs** resumes it. | open |
20 -| `needs-input` | The request form could not be read. | closed |
21 -| `waiting` | Another release PR is open. Request again after it finishes. | closed |
22 -| `blocked` | A release merged into `next` but was never tagged. Re-run its tag job or revert its release PR. | closed |
23 -| `empty` | No pending changesets for the selected languages. | closed |
24 -| `abandoned` | The release PR closed without merging. | closed |
25 -| `refused` | The release PR merged but failed the gate. Revert it, then request again. | closed |
14 +| State | Meaning | Issue |
15 +| ------------- | ------------------------------------------------------------------------------------------------------------- | ------ |
16 +| `in-review` | The release PR is open. | open |
17 +| `publishing` | The merged PR is tagged; the tag run is publishing. | open |
18 +| `published` | Every planned package is on its registry. | closed |
19 +| `failed` | A job failed or was cancelled. **Re-run failed jobs** resumes it. | open |
20 +| `needs-input` | The request form could not be read. | closed |
21 +| `waiting` | Another release PR is open. Request again after it finishes. | closed |
22 +| `blocked` | A release merged into `next` but was never tagged. See [Recover a failed release](#recover-a-failed-release). | closed |
23 +| `empty` | No pending changesets for the selected languages. | closed |
24 +| `abandoned` | The release PR closed without merging. | closed |
25 +| `refused` | The release PR merged but failed the gate. See [Recover a failed release](#recover-a-failed-release). | closed |
26
27 ## Request
28
@@ -45,29 +45,54 @@ A beta goes through the same release PR, approval, gate and tag as a stable rele
45
46 The release PR description lists each package's old and new version, the changesets it consumes or leaves for later, and links to the changelogs and regenerated references. It names the requester, who may not approve.
47
48 -1. Wait for the `SDK candidate (<language>)` and `SDK candidate smoke (<language>)` checks. The first builds the exact files that will be published. The second installs them in a clean project like a user would; for Python it also tests the new core with the latest published providers.
48 +1. Wait for the `SDK candidate (<language>)` and `SDK candidate smoke (<language>)` checks. The first builds the exact files that will be published. The second installs them in a clean project like a user would; for Python it also tests the new core with the latest published providers. A stable release also runs `SDK candidate docs`: it installs the docs against the candidate packages through a job-local registry, then runs the docs lint, type, snippet and build checks, so a guide that breaks against the new SDK blocks the release. The ordinary docs checks skip release PRs.
49 2. A repository writer who did not request the release approves the head.
50
51 Do not push to the release branch. The tag step accepts only the bot's commit, so a pushed commit (including **Update branch**) makes the merge fail the gate. To change the notes, fix the changesets on `next`, close the release PR, and request a new release.
52
53 ## Merge and publish
54
55 -A person merges the approved, green release PR under normal `next` protection. On merge, the `tag` job checks that the head is the bot's commit, the approval, and the candidate checks (plus the docs check for a stable release), then tags the head `sdk-release/<id>`. If the gate refuses the release it creates no tag and comments the fix on the PR: revert the release PR on `next`, then request the release again. Closing the release PR without merging abandons the release.
55 +A person merges the approved, green release PR under normal `next` protection. On merge, the `tag` job checks that the head is the bot's commit, the approval, and the candidate checks (plus `SDK candidate docs` for a stable release), then tags the head `sdk-release/<id>`. If the gate refuses the release it creates no tag and comments on the PR; [Recover a failed release](#recover-a-failed-release) says what to do next. Closing the release PR without merging abandons the release.
56
57 The tag run then:
58
59 1. Pins the candidate artifacts built on the release PR by ID and digest. It never rebuilds.
60 -2. Uploads only the files npm and PyPI are missing. An existing file with identical bytes is accepted; different bytes stop the run with a conflict. npm versions are uploaded under a release-only dist-tag. Once every upload is visible and each tarball's provenance names `sdk.release.yml` at this release's tag and describes the reviewed bytes, the channel's tag (`latest` or `next`) moves forward and the release-only tag is removed. A failed provenance check leaves the channel tag where it was.
61 -3. Checks what users get: `npm audit signatures` passes on a fresh install, each PyPI file is attested by `sdk.release.yml` in `pypi-release`, and `pypi-attestations` verifies the signature.
62 -4. For a stable release, opens a docs PR that pins the released npm versions in `docs/package.json` and `docs/bun.lock`. Merging that PR after its checks pass is what makes twoslash type-check the docs against the released types.
60 +2. Logs in to npm through trusted publishing for every planned package and prints npm's answer for each. If npm refuses any package, the job fails before uploading anything and names the package and npm's reason. See [npm trusted publishing](#npm-trusted-publishing).
61 +3. Uploads only the files npm and PyPI are missing. An existing file with identical bytes is accepted; different bytes stop the run with a conflict. npm versions are uploaded under a release-only dist-tag. npm scans each new version before serving it, which takes about 5 to 15 minutes, so the job polls with backoff for up to 20 minutes for each upload to become visible and for its provenance; a re-run during the scan does not upload again. Once every upload is visible and each tarball's provenance names `sdk.release.yml` at this release's tag and describes the reviewed bytes, the channel's tag (`latest` or `next`) moves forward and the release-only tag is removed. A failed provenance check leaves the channel tag where it was.
62 +4. Checks what users get: `npm audit signatures` passes on a fresh install, each PyPI file is attested by `sdk.release.yml` in `pypi-release`, and `pypi-attestations` verifies the signature.
63 +5. For a stable release, opens a docs PR that pins the released npm versions in `docs/package.json` and `docs/bun.lock`. Merging that PR after its checks pass is what makes twoslash type-check the docs against the released types.
64
65 The last job of each stage shows the outcome on the request issue, including failed and cancelled jobs.
66
67 ## Recover a failed release
68
68 -Open the tag run and choose **Re-run failed jobs**. A re-run publishes the same pinned files, skips files already published, and uploads the rest. This works while the candidate artifacts exist, 30 days from the candidate build.
69 +Pick the row that matches what happened.
70
70 -If the artifacts expired, or a registry already serves different bytes, add changesets for the affected packages on `next` and request a new release. It plans from the versions in `next`, so the unpublished versions are skipped and the packages move to the next version.
71 +| Situation | Action |
72 +| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
73 +| The tag job failed on a GitHub error (5xx, timeout, rate limit) | Open the run and choose **Re-run failed jobs**. Creating the tag is safe to repeat. |
74 +| The gate refused the release because of a bug in the gate, now fixed on `next` | Run **SDK release** on `next` in Actions with action `regate`. |
75 +| The gate refused the release because the release was wrong (approval, checks, head) | Revert the release PR on `next`, fix the cause, then request the release again. |
76 +| The candidate artifacts expired (30 days after the candidate build) | Revert the release PR on `next`, then request the release again. |
77 +| The tag exists but publishing failed | Open the tag run and choose **Re-run failed jobs**. |
78 +
79 +A re-run of the tag job runs the gate as `next` had it before the merge, so it repeats a gate bug. `regate` runs the gate as `next` has it now. It finds the release from the plan `next` carries and its release PR from the branch name, so it cannot be pointed at another PR or commit, and it applies exactly the same checks: the bot's head, an independent approval of that head, and green candidate checks. It tags the reviewed head if the release passes, does nothing if that tag already exists, and shares a concurrency group with the tag job. The new tag starts publishing as usual, and the request issue reopens.
80 +
81 +A re-run of the tag run publishes the same pinned files, skips files already published, and uploads the rest. This works while the candidate artifacts exist, 30 days from the candidate build. If a registry already serves different bytes, add changesets for the affected packages on `next` and request a new release. It plans from the versions in `next`, so the unpublished versions are skipped and the packages move to the next version.
82 +
83 +While a merged release is untagged, new requests end as `blocked`. Recover it first.
84 +
85 +### GitHub incidents
86 +
87 +Before reopening a PR whose checks never started, or re-running jobs that failed on GitHub errors, check [githubstatus.com](https://www.githubstatus.com). During an Actions incident, runs start late or not at all; wait for the incident to resolve, then re-run. On 2026-11-09, the docs pin PR started no checks because of an Actions incident, not a workflow defect.
88 +
89 +### npm trusted publishing
90 +
91 +npm publishing logs in with the GitHub OIDC token, never a stored npm token. The job checks the login for every planned package before uploading and prints npm's answer for each.
92 +
93 +- **`refused ... (404)` or `ENEEDAUTH`:** the package has no trusted publisher matching repository `ComposioHQ/composio`, workflow `sdk.release.yml`, environment `npm-release`, or npm dropped it. npm drops a new trusted publisher that has not published within 2 days. Fix it on npmjs.com → package → Settings → Trusted publishing, then re-run the failed jobs.
94 +- **`This trusted publisher cannot manage dist-tags`:** enable **Allow npm dist-tag** on the same settings page, then re-run the failed jobs. The npm CLI cannot change this setting; only the website can.
95 +- Check a package's publishers with `npm trust list <package>` (needs a maintainer login with 2FA).
96
97 ## Verify a release yourself
98
@@ -106,18 +131,18 @@ Put prose types such as `Array<Tool>` in code spans because summaries become MDX
131
132 ## Documentation
133
109 -- The release PR commits the SDK reference docs, generated from the released source, and the docs changelog entry. Changelog snippets are not type-checked, because they may describe APIs released after the docs pins.
110 -- The docs pin PR moves the docs to the released npm versions. Twoslash then checks every guide snippet against those types.
134 +- The release PR commits the SDK reference docs, generated from the released source, and the docs changelog entry. `Docs - SDK reference drift` regenerates both references on every PR to `next` that changes SDK sources or the generators, so the release PR only changes version strings in them. Changelog snippets are not type-checked, because they may describe APIs released after the docs pins.
135 +- `SDK candidate docs` checks every guide snippet against the release's candidate packages before approval. The docs pin PR then moves the docs to the released npm versions.
136 - `docs.sdk-change-sync.yml` keeps updating guides for SDK source changes; it no longer touches the version pins.
137
138 ## Owner setup
139
140 Complete these hosted prerequisites before the first release.
141
117 -1. Install a dedicated SDK release App with repository Contents, Pull requests, and Issues write, Actions read, and organization Members read. It needs no protection bypass on `next`. Set the `SDK_RELEASE_APP_SLUG` and `SDK_RELEASE_APP_CLIENT_ID` variables. Put `SDK_RELEASE_APP_PRIVATE_KEY` only in the `sdk-release-control` environment, restricted to `next`.
142 +1. Install a dedicated SDK release App with repository Contents, Pull requests, and Issues write, Actions read, and organization Members read. It needs no protection bypass on `next`. Set the `SDK_RELEASE_APP_SLUG` and `SDK_RELEASE_APP_CLIENT_ID` variables. Put `SDK_RELEASE_APP_PRIVATE_KEY` only in the `sdk-release-control` environment, restricted to `next`. Every release job uses this pair, except the post-publish `docs` job: it runs on the release tag, which `sdk-release-control` does not admit, so it opens the docs pin PR with the `RELEASE_BOT_*` pair. Both pairs belong to the same App.
143 2. Protect `sdk-release/*` tags against creation, update, and deletion, with only this App allowed to bypass. Publishing trusts these tags, so check that an ordinary writer cannot create or move one.
144 3. Create `npm-release` and `pypi-release` environments that deploy only from `sdk-release/*` tags.
120 -4. Register trusted publishers for `.github/workflows/sdk.release.yml` with the `npm-release` environment on every npm package, and with `pypi-release` on every PyPI package. Always set the environment: PyPI treats a publisher without one as matching any environment. On npm, enable **Allow npm dist-tag**, because the publish job moves `latest` or `next` and removes the release-only tag with `npm dist-tag`. Register shortly before the first release, because npm drops a new trusted publisher that hasn't published within 2 days. Keep the existing `ts.release.yml` and `py.release.yml` publishers. npm allows up to 10 trusted publishers per package and PyPI accepts several, so the `main` beta lane and core prereleases keep publishing.
145 +4. Register trusted publishers for `.github/workflows/sdk.release.yml` with the `npm-release` environment on every npm package, and with `pypi-release` on every PyPI package. Always set the environment: PyPI treats a publisher without one as matching any environment. On npm, enable **Allow npm dist-tag**, because the publish job moves `latest` or `next` and removes the release-only tag with `npm dist-tag`. Register within 2 days before the first release through this workflow, because npm drops a new trusted publisher that hasn't published within 2 days. **Allow npm dist-tag** can only be set on the npm website, not with the CLI. Confirm each package with `npm trust list <package>`. Keep the existing `ts.release.yml` and `py.release.yml` publishers. npm allows up to 10 trusted publishers per package and PyPI accepts several, so the `main` beta lane and core prereleases keep publishing.
146 5. Restrict pushes to `sdk-release/batch-*` branches to the App. The tag step refuses heads the App did not commit, so this only prevents confusion.
147 6. Keep Actions artifact retention at 30 days or more.
148
ts/packages/core/scripts/README.md
+1 -1
@@ -22,4 +22,4 @@ pnpm generate:docs
22
23 ## CI
24
25 -`.github/workflows/generate-sdk-docs.yml` triggers on changes to `ts/packages/core/src/**` and opens a PR with updated docs.
25 +`.github/workflows/docs-sdk-reference-drift.yml` regenerates the reference on PRs to `next` that change `ts/packages/core/src/**` or this generator, and fails if the committed output differs.
uv.lock
+30
@@ -523,6 +523,9 @@ dev = [
523 { name = "tomli" },
524 { name = "twine" },
525 ]
526 +docs-reference = [
527 + { name = "griffe" },
528 +]
529 docs-snippets = [
530 { name = "mypy" },
531 ]
@@ -563,6 +566,7 @@ dev = [
566 { name = "tomli", specifier = ">=2.0.2,<2.1" },
567 { name = "twine", specifier = ">=6.2.0" },
568 ]
569 +docs-reference = [{ name = "griffe", specifier = "==2.3.0" }]
570 docs-snippets = [{ name = "mypy", specifier = "==2.3.1" }]
571 release = [
572 { name = "build", specifier = "==1.6.1" },
@@ -1072,6 +1076,32 @@ wheels = [
1076 { url = "https://files.pythonhosted.org/packages/91/4c/e0ce1ef95d4000ebc1c11801f9b944fa5910ecc15b5e351865763d8657f8/graphviz-0.21-py3-none-any.whl", hash = "sha256:54f33de9f4f911d7e84e4191749cac8cc5653f815b06738c54db9a15ab8b1e42", size = 47300, upload-time = "2025-06-15T09:35:04.433Z" },
1077 ]
1078
1079 +[[package]]
1080 +name = "griffe"
1081 +version = "2.3.0"
1082 +source = { registry = "https://pypi.org/simple" }
1083 +dependencies = [
1084 + { name = "griffecli" },
1085 + { name = "griffelib" },
1086 +]
1087 +sdist = { url = "https://files.pythonhosted.org/packages/d5/03/75ca4d08a7eff164292d42cf72c7c510423b3414e66205f0ba5b35ad3034/griffe-2.3.0.tar.gz", hash = "sha256:aa5634c0d7802583ecd29a7fe335c02d462ffdf5ce8f51426a3d326f374e6d93", size = 247493, upload-time = "2026-09-04T15:08:15.364Z" }
1088 +wheels = [
1089 + { url = "https://files.pythonhosted.org/packages/61/f9/8bfacdb992aed404a3a53694689759841635bce93b86ddb621c1d7f2558c/griffe-2.3.0-py3-none-any.whl", hash = "sha256:92a41ff72eb1eb316cdcb7248a608f1313f9fbc6e35d5cffa5cf7c813b7db70b", size = 5072, upload-time = "2026-09-04T15:08:14.074Z" },
1090 +]
1091 +
1092 +[[package]]
1093 +name = "griffecli"
1094 +version = "2.3.0"
1095 +source = { registry = "https://pypi.org/simple" }
1096 +dependencies = [
1097 + { name = "colorama" },
1098 + { name = "griffelib" },
1099 +]
1100 +sdist = { url = "https://files.pythonhosted.org/packages/5c/15/f70539f7efb44f27d209b43e386b1a5397bd476879ff19a206b75454f58e/griffecli-2.3.0.tar.gz", hash = "sha256:916fdc851cf51d38e9b5ab82550305df45e5981d5dfe65d346544464abedb3ec", size = 59676, upload-time = "2026-09-04T15:08:16.426Z" }
1101 +wheels = [
1102 + { url = "https://files.pythonhosted.org/packages/06/8c/8ffa4272d6bf85a0abe8898ef74ef41d505317bb4103e14a11d45d799dce/griffecli-2.3.0-py3-none-any.whl", hash = "sha256:f94653edcb52ebcac21eaeb3b7121b065a636174eddf2bd558b5935e72a553e8", size = 11593, upload-time = "2026-09-04T15:08:11.739Z" },
1103 +]
1104 +
1105 [[package]]
1106 name = "griffelib"
1107 version = "2.3.0"