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

next
ts 498 lines 20 KB
Raw
1 import { Config, Effect, Option, Path, Schema, Stdio, Stream } from 'effect';
2 import { Base64 } from 'effect/encoding';
3 import { mergeCommitOf, readReleasePull, trustedIssue, verifyReleaseGate } from './approval';
4 import {
5 CONTENT_CONCURRENCY,
6 CreatedSha,
7 GitHub,
8 PositiveInt,
9 REPOSITORY_PATH,
10 RunId,
11 Sha,
12 TagRef,
13 commentIssue,
14 fileAt,
15 fileAtOrNull,
16 paginateArray,
17 request,
18 requestOptional,
19 requireActiveMember,
20 runUrl,
21 } from './github';
22 import { createSdkReleasePlan, type SdkReleasePlan } from './plan';
23 import {
24 PullDetail,
25 PullListItem,
26 isReleasePull,
27 releaseBranch,
28 releasePullBody,
29 releasePullTitle,
30 } from './release-pr';
31 import { ReleaseRequest, parseReleaseRequest } from './request';
32 import {
33 appendFile,
34 ensure,
35 fail,
36 readJson,
37 runMain,
38 sameJson,
39 type ReleaseServices,
40 } from './runtime';
41 import {
42 BATCH_PATH,
43 ReleaseBatch,
44 ReleasePatch,
45 releaseOutputs,
46 releaseTag,
47 validateBatchDiff,
48 } from './source';
49 import { RECOVERY_RUNBOOK, ReleaseState } from './state';
50
51 const GitCommit = Schema.Struct({
52 sha: Sha,
53 tree: Schema.Struct({ sha: Sha }),
54 parents: Schema.Array(Schema.Struct({ sha: Sha })),
55 });
56 const CreatedRef = Schema.Struct({ ref: Schema.String });
57
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`,
61 PullListItem
62 ).pipe(Stream.filter(isReleasePull), Stream.runHead);
63
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);
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 -----------------------------------------------------------------------------------
91
92 export interface ReleaseRequestContext {
93 readonly actor: string;
94 readonly runId: string;
95 readonly sourceSha: string;
96 readonly issueNumber?: number;
97 /** The release App, whose commits alone may name a request issue. */
98 readonly appSlug: string;
99 }
100
101 /** A request either ends the request stage or plans a batch for the release PR jobs. */
102 export type RequestOutcome =
103 { readonly _tag: 'Planned'; readonly batch: ReleaseBatch } | ReleaseState;
104
105 /** The outcome, and the request issue the status job shows it on, when there is one. */
106 export interface RequestResult {
107 readonly outcome: RequestOutcome;
108 readonly issue: Option.Option<number>;
109 }
110
111 /** Opens the tracking issue for a dispatch-started release; issue-form requests already have one. */
112 const createRequestIssue = (run: string) =>
113 Effect.map(
114 request('POST', `${REPOSITORY_PATH}/issues`, Schema.Struct({ number: PositiveInt }), {
115 title: `SDK release ${run}`,
116 body: `Requested from ${runUrl(run)}. The release PR, publication result and any failure are reported here.`,
117 }),
118 issue => issue.number
119 );
120
121 /**
122 * Checks that the requester is an active ComposioHQ member, then decides the request: resume
123 * its own open release PR, wait for another one, refuse while an untagged release sits on
124 * `next`, or plan versions. The request issue shows the outcome; nothing is posted here.
125 */
126 export const executeReleaseRequest = <E, R>(
127 parse: Effect.Effect<ReleaseRequest, string>,
128 context: ReleaseRequestContext,
129 plan: (request: ReleaseRequest) => Effect.Effect<SdkReleasePlan, E, R>
130 ) =>
131 Effect.gen(function* () {
132 yield* requireActiveMember(context.actor);
133 return yield* parse.pipe(
134 Effect.matchEffect({
135 onFailure: reason =>
136 Effect.succeed<RequestResult>({
137 outcome: ReleaseState.make({ _tag: 'NeedsInput', reason }),
138 issue: Option.fromNullishOr(context.issueNumber),
139 }),
140 onSuccess: releaseRequest => decideRequest(releaseRequest, context, plan),
141 })
142 );
143 });
144
145 const decideRequest = <E, R>(
146 releaseRequest: ReleaseRequest,
147 context: ReleaseRequestContext,
148 plan: (request: ReleaseRequest) => Effect.Effect<SdkReleasePlan, E, R>
149 ) =>
150 Effect.gen(function* () {
151 const requestIssue = Option.fromNullishOr(context.issueNumber);
152 const decided = (outcome: ReleaseState, issue = requestIssue): RequestResult => ({
153 outcome,
154 issue,
155 });
156 const current = yield* activeRelease;
157 if (Option.isSome(current) && current.value.head.ref === releaseBranch(context.runId)) {
158 // A re-run of a dispatch has no issue in its event; its release PR's plan names it.
159 const issue = Option.isSome(requestIssue)
160 ? requestIssue
161 : yield* Effect.flatMap(readReleasePull(current.value.number), ({ pull, batch }) =>
162 trustedIssue(pull, batch, context.appSlug)
163 );
164 return decided(ReleaseState.make({ _tag: 'InReview', pull: current.value.html_url }), issue);
165 }
166 if (Option.isSome(current))
167 return decided(ReleaseState.make({ _tag: 'Waiting', pull: current.value.html_url }));
168 const untagged = yield* untaggedRelease(context.sourceSha);
169 if (Option.isSome(untagged))
170 return decided(ReleaseState.make({ _tag: 'Blocked', release: untagged.value }));
171 const selected = yield* plan(releaseRequest);
172 if (!selected.releases.length) return decided(ReleaseState.make({ _tag: 'Empty' }));
173 const issue = context.issueNumber ?? (yield* createRequestIssue(context.runId));
174 const batch = yield* Schema.decodeUnknownEffect(ReleaseBatch)({
175 id: context.runId,
176 inputBase: context.sourceSha,
177 requestedBy: context.actor,
178 issue,
179 date: new Date().toISOString().slice(0, 10),
180 plan: selected,
181 });
182 // The batch travels as one environment variable, which Linux caps at 128 KiB.
183 yield* ensure(
184 new TextEncoder().encode(JSON.stringify(batch)).length < 120_000,
185 'Release batch is too large to pass between jobs'
186 );
187 return { outcome: { _tag: 'Planned', batch }, issue: Option.some(issue) } as RequestResult;
188 });
189
190 // 2. release PR --------------------------------------------------------------------------------
191
192 /** Commits the prepared files on top of the frozen source and points the release branch at it. */
193 const commitReleaseBranch = (batch: ReleaseBatch, patch: ReleasePatch) =>
194 Effect.gen(function* () {
195 const source = yield* request(
196 'GET',
197 `${REPOSITORY_PATH}/git/commits/${batch.inputBase}`,
198 GitCommit
199 );
200 const blobs = yield* Effect.forEach(
201 patch.files,
202 file =>
203 file.after === null
204 ? Effect.succeed({
205 path: file.path,
206 mode: '100644',
207 type: 'blob',
208 sha: null as string | null,
209 })
210 : Effect.map(
211 request('POST', `${REPOSITORY_PATH}/git/blobs`, CreatedSha, {
212 content: Base64.encode(file.after),
213 encoding: 'base64',
214 }),
215 blob => ({ path: file.path, mode: '100644', type: 'blob', sha: blob.sha })
216 ),
217 { concurrency: CONTENT_CONCURRENCY }
218 );
219 const tree = yield* request('POST', `${REPOSITORY_PATH}/git/trees`, CreatedSha, {
220 base_tree: source.tree.sha,
221 tree: blobs,
222 });
223 const commit = yield* request('POST', `${REPOSITORY_PATH}/git/commits`, CreatedSha, {
224 message: 'chore(release): prepare SDK versions and documentation',
225 parents: [batch.inputBase],
226 tree: tree.sha,
227 });
228 const branch = releaseBranch(batch.id);
229 // A re-run of this job replaces its own branch; the batch ID is unique to the request run.
230 const existing = yield* requestOptional(
231 `${REPOSITORY_PATH}/git/ref/heads/${branch}`,
232 CreatedRef
233 );
234 if (Option.isSome(existing))
235 yield* request('PATCH', `${REPOSITORY_PATH}/git/refs/heads/${branch}`, CreatedRef, {
236 sha: commit.sha,
237 force: true,
238 });
239 else
240 yield* request('POST', `${REPOSITORY_PATH}/git/refs`, CreatedRef, {
241 ref: `refs/heads/${branch}`,
242 sha: commit.sha,
243 });
244 return branch;
245 });
246
247 /** Checks the prepared patch is release-only for `batch`, commits it and opens the release PR. */
248 export const openReleasePull = (cwd: string, planned: ReleaseBatch, value: unknown) =>
249 Effect.gen(function* () {
250 // Decoding both sides puts their keys in schema order, so the JSON comparison below is exact.
251 const batch = yield* Schema.decodeUnknownEffect(ReleaseBatch)(planned);
252 const patch = yield* Schema.decodeUnknownEffect(ReleasePatch)(value);
253 const current = yield* activeRelease;
254 // A re-run after the PR opened finds its own PR; any other open release PR wins.
255 if (Option.isSome(current))
256 return ReleaseState.make({
257 _tag: current.value.head.ref === releaseBranch(batch.id) ? 'InReview' : 'Waiting',
258 pull: current.value.html_url,
259 });
260 // Another release may have merged and failed its gate since this one was planned.
261 const next = yield* request('GET', `${REPOSITORY_PATH}/git/ref/heads/next`, TagRef);
262 const untagged = yield* untaggedRelease(next.object.sha);
263 if (Option.isSome(untagged))
264 return ReleaseState.make({ _tag: 'Blocked', release: untagged.value });
265 const frozen = yield* Effect.forEach(
266 patch.files,
267 file => fileAtOrNull(file.path, batch.inputBase),
268 { concurrency: CONTENT_CONCURRENCY }
269 );
270 for (const [index, file] of patch.files.entries())
271 yield* ensure(
272 frozen[index] === file.before,
273 `Prepared input differs from frozen source: ${file.path}`
274 );
275 const planFile = patch.files.find(file => file.path === BATCH_PATH)?.after;
276 yield* ensure(
277 planFile !== undefined &&
278 planFile !== null &&
279 sameJson(
280 yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ReleaseBatch))(planFile),
281 batch
282 ),
283 'Prepared release plan differs from the planned batch'
284 );
285 const outputs = yield* releaseOutputs(cwd, batch);
286 yield* validateBatchDiff(patch.files, batch, outputs);
287 const branch = yield* commitReleaseBranch(batch, patch);
288 const pull = yield* request('POST', `${REPOSITORY_PATH}/pulls`, PullDetail, {
289 title: releasePullTitle(batch),
290 head: branch,
291 base: 'next',
292 body: releasePullBody(batch, branch, outputs),
293 });
294 return ReleaseState.make({ _tag: 'InReview', pull: pull.html_url });
295 });
296
297 // 3. tag ---------------------------------------------------------------------------------------
298
299 /**
300 * Decides a closed release PR. An unmerged PR is abandoned. A merged one is tagged on its reviewed
301 * head only if it passes the release gate; a gate verdict refuses it and says so on the PR, while
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 */
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(
309 Effect.as(Option.none<string>()),
310 Effect.catchTag('ReleaseError', error => Effect.succeedSome(error.message))
311 );
312 if (Option.isSome(verdict)) {
313 yield* commentIssue(
314 pull.number,
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)}`,
322 GitCommit
323 );
324 yield* ensure(
325 merged.parents.some(parent => parent.sha === pull.head.sha) || merged.parents.length === 1,
326 'Unrecognized release merge topology'
327 );
328 const tag = releaseTag(batch.id);
329 const existing = yield* requestOptional(`${REPOSITORY_PATH}/git/ref/tags/${tag}`, TagRef);
330 yield* Option.match(existing, {
331 onSome: ref =>
332 ensure(
333 ref.object.type === 'commit' && ref.object.sha === pull.head.sha,
334 'Publication source tag already points to another source'
335 ),
336 onNone: () =>
337 request('POST', `${REPOSITORY_PATH}/git/refs`, CreatedRef, {
338 ref: `refs/tags/${tag}`,
339 sha: pull.head.sha,
340 }),
341 });
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({
396 token: Config.schema(Schema.NonEmptyString, 'SDK_RELEASE_TOKEN'),
397 runId: Config.schema(RunId, 'GITHUB_RUN_ID'),
398 sha: Config.schema(Sha, 'GITHUB_SHA'),
399 eventPath: Config.String('GITHUB_EVENT_PATH'),
400 eventName: Config.String('GITHUB_EVENT_NAME'),
401 outputPath: Config.String('GITHUB_OUTPUT'),
402 });
403 type Environment = Config.Success<typeof Environment>;
404
405 const EventEnvelope = Schema.Struct({
406 sender: Schema.Struct({ login: Schema.String }),
407 issue: Schema.optionalKey(Schema.Struct({ number: PositiveInt })),
408 pull_request: Schema.optionalKey(Schema.Struct({ number: PositiveInt })),
409 });
410
411 const plannedBatch = Config.schema(Schema.fromJsonString(ReleaseBatch), 'SDK_RELEASE_BATCH');
412
413 type Mode = (
414 env: Environment,
415 event: unknown,
416 envelope: typeof EventEnvelope.Type
417 ) => Effect.Effect<void, unknown, GitHub | ReleaseServices>;
418
419 /** Writes the request issue, when known, for the stage's status job. */
420 const outputIssue = (env: Environment, issue: Option.Option<number>) =>
421 Option.match(issue, {
422 onNone: () => Effect.void,
423 onSome: number => appendFile(env.outputPath, `issue=${number}\n`),
424 });
425
426 /** Writes a stage outcome as a job output for the stage's status job. */
427 const outputState = (env: Environment, state: ReleaseState) =>
428 appendFile(env.outputPath, `state=${JSON.stringify(state)}\n`);
429
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('.');
434 // Known before planning, so a failure is still reported on the request issue.
435 if (envelope.issue) yield* appendFile(env.outputPath, `issue=${envelope.issue.number}\n`);
436 const appSlug = yield* Config.String('SDK_RELEASE_APP_SLUG');
437 const { outcome, issue } = yield* executeReleaseRequest(
438 Effect.try({
439 try: () => parseReleaseRequest(env.eventName, event),
440 catch: error => (error instanceof Error ? error.message : 'Unreadable request'),
441 }),
442 {
443 actor: envelope.sender.login,
444 runId: env.runId,
445 sourceSha: env.sha,
446 appSlug,
447 ...(envelope.issue ? { issueNumber: envelope.issue.number } : {}),
448 },
449 choices => createSdkReleasePlan(cwd, { ...choices, run: env.runId })
450 );
451 yield* outcome._tag === 'Planned'
452 ? appendFile(env.outputPath, `batch=${JSON.stringify(outcome.batch)}\n`)
453 : outputState(env, outcome);
454 yield* outputIssue(env, issue);
455 }),
456 'release-pr': (env: Environment) =>
457 Effect.gen(function* () {
458 const [, patchPath] = yield* (yield* Stdio.Stdio).args;
459 if (!patchPath) return yield* fail('Expected the prepared patch path');
460 const state = yield* openReleasePull(
461 (yield* Path.Path).resolve('.'),
462 yield* plannedBatch,
463 yield* readJson(Schema.Unknown, patchPath)
464 );
465 yield* outputState(env, state);
466 }),
467 tag: (env: Environment, _event: unknown, envelope: typeof EventEnvelope.Type) =>
468 Effect.gen(function* () {
469 if (!envelope.pull_request) return yield* fail('Expected a closed release PR event');
470 const appSlug = yield* Config.String('SDK_RELEASE_APP_SLUG');
471 const { pull, batch } = yield* readReleasePull(envelope.pull_request.number);
472 const issue = yield* trustedIssue(pull, batch, appSlug);
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
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;
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);
495 yield* MODES[mode](env, event, envelope).pipe(Effect.provide(GitHub.layer(env.token)));
496 });
497
498 if (import.meta.main) runMain(main);