@chernabog/sdk 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/events.ts ADDED
@@ -0,0 +1,427 @@
1
+ // The GitHub events that can change what a flow's trigger finds, so a repo's
2
+ // workflow can run the plan job when one happens rather than only on its
3
+ // schedule (#455, #457). The catalogue declares them, as it declares the
4
+ // phases each source reads: each source names the events it depends on, and
5
+ // each block whose wakes find parked runs the events that settle the wait.
6
+ // A flow written in TypeScript declares its own with the same values, through
7
+ // `declare`.
8
+ //
9
+ // Each declaration also says how the event's payload names the work item, so
10
+ // the plan job can look at that one item rather than the whole repo, and
11
+ // which guards it keeps: that whoever caused the event is the repo's owner, a
12
+ // member or a collaborator, and that it wasn't the flow's own persona, so a
13
+ // flow doesn't wake itself in a loop. Both apply unless a declaration opts out.
14
+ //
15
+ // Phase advances aren't declared: a phase writer sends `repository_dispatch`
16
+ // `chernabog-phase`, and that wakes every flow whose sources read phases.
17
+ // `check_suite` can't be declared: GitHub starts no workflow for a check suite
18
+ // that Actions created, so waiting on CI is `workflow_run: completed`, filtered
19
+ // to the repo's CI workflows. Nor can `pull_request_target`: an agent never
20
+ // runs on it.
21
+
22
+ import type { Flow, Json } from "@chernabog/core";
23
+ import * as Arr from "effect/Array";
24
+ import * as Option from "effect/Option";
25
+ import * as Order from "effect/Order";
26
+ import * as Predicate from "effect/Predicate";
27
+ import * as Record from "effect/Record";
28
+ import * as Schema from "effect/Schema";
29
+
30
+ // The events a flow can declare.
31
+ export const EVENT_NAMES = [
32
+ "issues",
33
+ "issue_comment",
34
+ "pull_request",
35
+ "pull_request_review",
36
+ "workflow_run",
37
+ ] as const;
38
+
39
+ export type EventName = (typeof EVENT_NAMES)[number];
40
+
41
+ // What a phase writer sends after an advance, which wakes every flow whose
42
+ // sources read phases.
43
+ export const PHASE_EVENT = "repository_dispatch";
44
+
45
+ export const PHASE_TYPE = "chernabog-phase";
46
+
47
+ // The associations that may cause an event a guarded declaration wakes on.
48
+ export const TRUSTED = ["OWNER", "MEMBER", "COLLABORATOR"] as const;
49
+
50
+ // How an event's payload names the work item, by a dotted path into it:
51
+ // - issue, pull-request: the number at the path;
52
+ // - branch: the branch named at the path, such as a CI run's head branch;
53
+ // - item: the item's claim name at the path, `pr-7`, as a phase event says it;
54
+ // - repo: no one item, so the plan job looks at every one, as its sweep does.
55
+ export const ItemFrom = Schema.Union([
56
+ Schema.Struct({ kind: Schema.Literals(["issue", "pull-request"]), path: Schema.String }),
57
+ Schema.Struct({ kind: Schema.Literals(["branch", "item"]), path: Schema.String }),
58
+ Schema.Struct({ kind: Schema.Literal("repo") }),
59
+ ]);
60
+
61
+ export type ItemFrom = typeof ItemFrom.Type;
62
+
63
+ // One event a flow wakes on.
64
+ export const WakingEvent = Schema.Struct({
65
+ event: Schema.Literals(EVENT_NAMES),
66
+ // Its activity types, the payload's `action`: a workflow's `types:` filter.
67
+ types: Schema.NonEmptyArray(Schema.String),
68
+ item: ItemFrom,
69
+ // Where the payload says how whoever caused it relates to the repo, such as
70
+ // `comment.author_association`. None where only someone with triage or
71
+ // write access can cause it at all, such as labelling an issue.
72
+ association: Schema.optionalKey(Schema.String),
73
+ // Whether it wakes the flow only when that association is OWNER, MEMBER or
74
+ // COLLABORATOR.
75
+ trusted: Schema.Boolean,
76
+ // Whether an event the flow's own persona caused wakes it, as its own merge
77
+ // or its own push's CI run must.
78
+ ownPersona: Schema.Boolean,
79
+ });
80
+
81
+ export type WakingEvent = typeof WakingEvent.Type;
82
+
83
+ const decodeWaking = Schema.decodeUnknownSync(WakingEvent);
84
+
85
+ // A declaration, with the guards on unless it says otherwise: refused when
86
+ // the module loads if it names an event no flow may wake on.
87
+ export const on = (
88
+ event: EventName,
89
+ types: readonly [string, ...Array<string>],
90
+ item: ItemFrom,
91
+ options: {
92
+ readonly association?: string;
93
+ readonly trusted?: boolean;
94
+ readonly ownPersona?: boolean;
95
+ } = {},
96
+ ): WakingEvent =>
97
+ decodeWaking({
98
+ event,
99
+ types,
100
+ item,
101
+ ...Option.match(Option.fromUndefinedOr(options.association), {
102
+ onNone: () => ({}),
103
+ onSome: (association) => ({ association }),
104
+ }),
105
+ trusted: options.trusted ?? true,
106
+ ownPersona: options.ownPersona ?? false,
107
+ });
108
+
109
+ const issueNumber: ItemFrom = { kind: "issue", path: "issue.number" };
110
+ const pullRequestNumber: ItemFrom = { kind: "pull-request", path: "pull_request.number" };
111
+
112
+ // The events the catalogue's sources and wakes declare, which a flow written
113
+ // in TypeScript declares too, by what its trigger reads.
114
+
115
+ // A label on an issue, which queues it: only someone with triage access can
116
+ // apply one.
117
+ export const issueLabelled = on("issues", ["labeled"], issueNumber);
118
+
119
+ // A review asked of someone, or a draft marked ready, on a pull request whose
120
+ // author the repo trusts.
121
+ export const reviewRequested = on(
122
+ "pull_request",
123
+ ["review_requested", "ready_for_review"],
124
+ pullRequestNumber,
125
+ { association: "pull_request.author_association" },
126
+ );
127
+
128
+ // A review asked again, of a pull request whose author the repo trusts.
129
+ export const reviewRequestedAgain = on("pull_request", ["review_requested"], pullRequestNumber, {
130
+ association: "pull_request.author_association",
131
+ });
132
+
133
+ // A draft marked ready by its author, whom the repo trusts.
134
+ export const readyForReview = on("pull_request", ["ready_for_review"], pullRequestNumber, {
135
+ association: "pull_request.author_association",
136
+ });
137
+
138
+ // A review submitted by someone the repo trusts.
139
+ export const reviewSubmitted = on("pull_request_review", ["submitted"], pullRequestNumber, {
140
+ association: "review.author_association",
141
+ });
142
+
143
+ // A pull request closed, merged among them: only someone with write access
144
+ // merges one, and the persona's own merge counts.
145
+ export const pullRequestClosed = on("pull_request", ["closed"], pullRequestNumber, {
146
+ ownPersona: true,
147
+ });
148
+
149
+ // A pull request closed, which may have moved its base under every other open
150
+ // one, so no one item: the plan job looks at them all.
151
+ export const baseMoved = on("pull_request", ["closed"], { kind: "repo" }, { ownPersona: true });
152
+
153
+ // What moves an epic's layers, which changes its fingerprint and wakes its
154
+ // parked run (Epic.queued): a task closed or relabelled, a push to or a review
155
+ // of a layer's pull request, or its merge (baseMoved). None names the epic, so
156
+ // the plan job looks at every item. A task's close counts when the persona's
157
+ // own merge closes it.
158
+ export const taskChanged = on(
159
+ "issues",
160
+ ["closed", "labeled", "unlabeled"],
161
+ { kind: "repo" },
162
+ { ownPersona: true },
163
+ );
164
+
165
+ export const layerPushed = on("pull_request", ["synchronize"], { kind: "repo" });
166
+
167
+ export const layerReviewed = on(
168
+ "pull_request_review",
169
+ ["submitted"],
170
+ { kind: "repo" },
171
+ { association: "review.author_association" },
172
+ );
173
+
174
+ export const layerChanged = [taskChanged, layerPushed, layerReviewed, baseMoved];
175
+
176
+ // A CI run finished on a branch, the persona's own push's too. Filtered to the
177
+ // repo's CI workflows when the workflow is built.
178
+ export const ciCompleted = on(
179
+ "workflow_run",
180
+ ["completed"],
181
+ { kind: "branch", path: "workflow_run.head_branch" },
182
+ { ownPersona: true },
183
+ );
184
+
185
+ // A comment by someone the repo trusts.
186
+ export const commentCreated = on("issue_comment", ["created"], issueNumber, {
187
+ association: "comment.author_association",
188
+ });
189
+
190
+ // What a flow declares: the events that wake it, and whether its sources read
191
+ // phases, so a phase event wakes it too.
192
+ export const FlowEvents = Schema.Struct({
193
+ events: Schema.Array(WakingEvent),
194
+ readsPhases: Schema.Boolean,
195
+ });
196
+
197
+ export type FlowEvents = typeof FlowEvents.Type;
198
+
199
+ // A flow, carrying what it declares. Not enumerable, so the flow's keys stay
200
+ // those it was defined with, as a compiled flow's plan is carried.
201
+ export const declare = <Declaring extends Flow>(flow: Declaring, declared: FlowEvents): Declaring =>
202
+ Object.defineProperty(flow, "events", { value: declared, configurable: true });
203
+
204
+ const decodeFlowEvents = Schema.decodeUnknownOption(FlowEvents);
205
+
206
+ // What a flow declares, when it declares anything.
207
+ export const of = (flow: Flow): Option.Option<FlowEvents> => {
208
+ if (!Predicate.hasProperty(flow, "events")) {
209
+ return Option.none();
210
+ }
211
+
212
+ return decodeFlowEvents(flow.events);
213
+ };
214
+
215
+ // One of a repo's flows that runs in CI, as the plan job sees it: its name,
216
+ // the personas that run it, and what it declares.
217
+ export type CiFlow = {
218
+ readonly flow: string;
219
+ readonly personas: ReadonlyArray<string>;
220
+ readonly declared: FlowEvents;
221
+ };
222
+
223
+ // What the workflow says of an event in its `on:` block.
224
+ export type EventFilter = {
225
+ readonly types: ReadonlyArray<string>;
226
+ readonly workflows?: ReadonlyArray<string>;
227
+ };
228
+
229
+ // Which flows an event of these types wakes, how its payload names the item,
230
+ // and the guards it keeps.
231
+ export type Route = {
232
+ readonly event: string;
233
+ readonly types: ReadonlyArray<string>;
234
+ readonly flow: string;
235
+ readonly personas: ReadonlyArray<string>;
236
+ readonly item: ItemFrom;
237
+ readonly association: Option.Option<string>;
238
+ readonly trusted: boolean;
239
+ readonly ownPersona: boolean;
240
+ };
241
+
242
+ export type Wiring = {
243
+ // The workflow's `on:` block, by event, its keys in order.
244
+ readonly on: { readonly [event: string]: EventFilter };
245
+ // From each event to the flows and items it concerns.
246
+ readonly routes: ReadonlyArray<Route>;
247
+ // What was declared and left out, and why, for a person setting it up.
248
+ readonly notes: ReadonlyArray<string>;
249
+ };
250
+
251
+ // The work item an event concerns, as its payload names it.
252
+ export type EventItem =
253
+ | { readonly kind: "issue" | "pull-request"; readonly number: number }
254
+ | { readonly kind: "branch" | "item"; readonly name: string }
255
+ | { readonly kind: "repo" };
256
+
257
+ // A flow to run on an item, for a persona.
258
+ export type Woken = {
259
+ readonly flow: string;
260
+ readonly persona: string;
261
+ readonly item: EventItem;
262
+ };
263
+
264
+ const sorted = (names: ReadonlyArray<string>) => Arr.sort(Arr.dedupe(names), Order.String);
265
+
266
+ // The route a phase event takes to a flow whose sources read phases: any
267
+ // writer's advance, the persona's own among them, since only someone with
268
+ // write access can send one.
269
+ const phaseRoute = (flow: CiFlow): Route => ({
270
+ event: PHASE_EVENT,
271
+ types: [PHASE_TYPE],
272
+ flow: flow.flow,
273
+ personas: flow.personas,
274
+ item: { kind: "item", path: "client_payload.item" },
275
+ association: Option.none(),
276
+ trusted: false,
277
+ ownPersona: true,
278
+ });
279
+
280
+ // The `on:` block a repo's workflow needs for the flows it runs in CI, and
281
+ // the map from each event to the flows and items it concerns. `ciWorkflows`
282
+ // names the repo's CI workflows, which `workflow_run` is filtered to; `own`
283
+ // names chernabog's own workflow, which is never among them, since every run
284
+ // of it that a newer one replaces completes cancelled and would wake another.
285
+ // The workflow's schedule, which sweeps for what an event missed, is the
286
+ // caller's to add.
287
+ export const workflowOn = (
288
+ flows: ReadonlyArray<CiFlow>,
289
+ options: { readonly ciWorkflows: ReadonlyArray<string>; readonly own?: string },
290
+ ): Wiring => {
291
+ const ownName = Option.fromUndefinedOr(options.own);
292
+
293
+ const ciWorkflows = sorted(
294
+ options.ciWorkflows.filter((name) => !Option.exists(ownName, (own) => own === name)),
295
+ );
296
+
297
+ const declared: ReadonlyArray<Route> = flows.flatMap((flow) =>
298
+ flow.declared.events.map((waking): Route => ({
299
+ event: waking.event,
300
+ types: sorted(waking.types),
301
+ flow: flow.flow,
302
+ personas: flow.personas,
303
+ item: waking.item,
304
+ association: Option.fromUndefinedOr(waking.association),
305
+ trusted: waking.trusted,
306
+ ownPersona: waking.ownPersona,
307
+ })),
308
+ );
309
+
310
+ const unfiltered = (route: Route) => route.event === "workflow_run" && ciWorkflows.length === 0;
311
+
312
+ const routes = [
313
+ ...declared.filter((route) => !unfiltered(route)),
314
+ ...flows.flatMap((flow) =>
315
+ Arr.filter([flow], (one) => one.declared.readsPhases).map(phaseRoute),
316
+ ),
317
+ ];
318
+
319
+ const notes = sorted(
320
+ declared.flatMap((route) => Arr.filter([route.flow], () => unfiltered(route))),
321
+ ).map(
322
+ (flow) =>
323
+ `${flow} wakes on workflow_run, but the repo names no CI workflow to filter it to, so it waits for the schedule`,
324
+ );
325
+
326
+ const events = sorted(routes.map((route) => route.event));
327
+
328
+ const filters = Object.fromEntries(
329
+ events.map((event): readonly [string, EventFilter] => {
330
+ const types = sorted(
331
+ routes.filter((route) => route.event === event).flatMap((route) => route.types),
332
+ );
333
+
334
+ return [
335
+ event,
336
+ Option.match(
337
+ Option.liftPredicate(ciWorkflows, () => event === "workflow_run"),
338
+ {
339
+ onNone: () => ({ types }),
340
+ onSome: (workflows) => ({ workflows, types }),
341
+ },
342
+ ),
343
+ ];
344
+ }),
345
+ );
346
+
347
+ return { on: filters, routes, notes };
348
+ };
349
+
350
+ const asObject = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json));
351
+
352
+ // The value at a dotted path into a payload.
353
+ const at = (payload: Json, path: string): Option.Option<Json> =>
354
+ path
355
+ .split(".")
356
+ .reduce<Option.Option<Json>>(
357
+ (found, key) =>
358
+ Option.flatMap(found, (value) =>
359
+ Option.flatMap(asObject(value), (object) => Record.get(object, key)),
360
+ ),
361
+ Option.some(payload),
362
+ );
363
+
364
+ const numberAt = (payload: Json, path: string) =>
365
+ Option.filter(at(payload, path), (value): value is number => Number.isInteger(value));
366
+
367
+ const nameAt = (payload: Json, path: string) =>
368
+ Option.filter(
369
+ at(payload, path),
370
+ (value): value is string => Predicate.isString(value) && value.length > 0,
371
+ );
372
+
373
+ const itemOf = (from: ItemFrom, payload: Json): Option.Option<EventItem> => {
374
+ switch (from.kind) {
375
+ case "repo":
376
+ return Option.some({ kind: "repo" });
377
+ case "issue":
378
+ case "pull-request":
379
+ return Option.map(numberAt(payload, from.path), (number) => ({ kind: from.kind, number }));
380
+ case "branch":
381
+ case "item":
382
+ return Option.map(nameAt(payload, from.path), (name) => ({ kind: from.kind, name }));
383
+ }
384
+ };
385
+
386
+ const trustedBy = (route: Route, payload: Json) =>
387
+ !route.trusted ||
388
+ Option.match(route.association, {
389
+ onNone: () => true,
390
+ onSome: (path) =>
391
+ Option.exists(nameAt(payload, path), (association) =>
392
+ TRUSTED.some((trusted) => trusted === association),
393
+ ),
394
+ });
395
+
396
+ const sameLogin = (one: string, other: string) => one.toLowerCase() === other.toLowerCase();
397
+
398
+ // The flows an event wakes, each for every persona that runs it, and the item
399
+ // its payload names: none when a guard refuses it, when no route takes its
400
+ // type, or when its payload doesn't name the item where its declaration says.
401
+ // `action` is the event's activity type, as a workflow reads it.
402
+ export const wokenBy = (
403
+ routes: ReadonlyArray<Route>,
404
+ event: string,
405
+ payload: Json,
406
+ ): ReadonlyArray<Woken> => {
407
+ const action = nameAt(payload, "action");
408
+ const sender = nameAt(payload, "sender.login");
409
+
410
+ return routes
411
+ .filter(
412
+ (route) =>
413
+ route.event === event &&
414
+ Option.exists(action, (type) => route.types.includes(type)) &&
415
+ trustedBy(route, payload),
416
+ )
417
+ .flatMap((route) =>
418
+ Option.toArray(itemOf(route.item, payload)).flatMap((item) =>
419
+ route.personas
420
+ .filter(
421
+ (persona) =>
422
+ route.ownPersona || !Option.exists(sender, (login) => sameLogin(login, persona)),
423
+ )
424
+ .map((persona) => ({ flow: route.flow, persona, item })),
425
+ ),
426
+ );
427
+ };
@@ -30,6 +30,7 @@ import {
30
30
  } from "./block.ts";
31
31
  import * as Hybrid from "./hybrid.ts";
32
32
  import * as Implement from "./implement.ts";
33
+ import { PHASES } from "./phases.ts";
33
34
  import * as Review from "./review.ts";
34
35
  import * as Settings from "./settings.ts";
35
36
 
@@ -269,6 +270,10 @@ export const humanInitiatedBlocks = {
269
270
  },
270
271
  outcomes: {},
271
272
  mustRoute: [],
273
+ records: [
274
+ { item: "pull-request", phase: PHASES.pullRequest.reviewAsked },
275
+ { item: "issue", phase: PHASES.issue.handedOff },
276
+ ],
272
277
  contributes: { settings: Settings.Reviewers.fields, doctor: [Review.poolCheck] },
273
278
  }),
274
279
  };
package/src/hybrid.ts CHANGED
@@ -42,10 +42,12 @@ import {
42
42
  claimedBase,
43
43
  dropInProgress,
44
44
  issueItem,
45
+ landedBase,
45
46
  latestClaim,
46
47
  legacyClaim,
47
48
  markClaimed,
48
49
  PullRequestRef,
50
+ recordHandOff,
49
51
  sessionIdFor,
50
52
  } from "./implement.ts";
51
53
  import { renderPromptOr } from "./prompt.ts";
@@ -118,7 +120,7 @@ export const claim = (issue: number, options: BaseOptions = {}) =>
118
120
  const run = yield* Run;
119
121
  const branch = branchFor(issue);
120
122
  const item = Claims.issue(issue);
121
- const base = yield* baseOf(options);
123
+ const base = yield* landedBase(yield* baseOf(options));
122
124
  const baseSha = yield* baseHead(base);
123
125
  const claimed = yield* Claims.acquire(item, { withPerson: true });
124
126
 
@@ -311,6 +313,7 @@ export const handOff = (issue: number, pullRequest: PullRequestRef, finished: Fi
311
313
  `Worked on by a person with ${repo.agent} for #${issue}. ${sessionMarker.write(session)}`,
312
314
  );
313
315
  yield* dropInProgress(issue);
316
+ yield* recordHandOff(issue, pullRequest.number, {});
314
317
  yield* github.comment(
315
318
  issue,
316
319
  `Pull request ready for review: ${pullRequest.url}\n\n${finished.summary}`,
package/src/implement.ts CHANGED
@@ -51,6 +51,7 @@ import * as Stream from "effect/Stream";
51
51
 
52
52
  import * as Ci from "./ci.ts";
53
53
  import { ADDRESS, CONSIDER } from "./default-prompts.ts";
54
+ import * as Phases from "./phases.ts";
54
55
  import { LABELS as PLAN_LABELS } from "./plan-labels.ts";
55
56
  import { renderPrompt, renderPromptOr } from "./prompt.ts";
56
57
  import { requestReview } from "./pull-request.ts";
@@ -306,9 +307,40 @@ export const Claimed = Schema.Struct({
306
307
  // issue is taken on, rather than the issue implemented again (see claim).
307
308
  export type AdoptOptions = { readonly adopt?: boolean };
308
309
 
309
- // The head of the base to create the claim branch from. A base that is gone,
310
- // such as another task's branch merged and deleted, fails the claim: choosing
311
- // another is the flow's to do.
310
+ // Where work given `base` builds: `base`, or, when it is the branch of a pull
311
+ // request that merged, such as the task below an epic's task merged between
312
+ // the round that read it ready and its claim, the branch that one merged
313
+ // into, and on down as far as the layers below merged too. Stops at the
314
+ // flow's integration base, and at a branch with no merged pull request.
315
+ export const landedBase = (base: string) =>
316
+ Effect.gen(function* () {
317
+ const github = yield* GitHub;
318
+ const integration = yield* Settings.base;
319
+ const seen = new Set<string>();
320
+ let target = base;
321
+
322
+ while (target !== integration && !seen.has(target)) {
323
+ seen.add(target);
324
+
325
+ const below = Option.filter(
326
+ yield* github.pullRequestForBranch(target),
327
+ (pull) => pull.state === "merged",
328
+ );
329
+
330
+ if (Option.isNone(below)) {
331
+ break;
332
+ }
333
+
334
+ target = below.value.baseRef;
335
+ }
336
+
337
+ return target;
338
+ });
339
+
340
+ // The head of the base to create the claim branch from. A base that is gone
341
+ // with no merged pull request to follow (see landedBase), such as another
342
+ // task's branch deleted unmerged, fails the claim: choosing another is the
343
+ // flow's to do.
312
344
  export const baseHead = (base: string) =>
313
345
  Effect.gen(function* () {
314
346
  const sha = yield* (yield* GitHub).branchSha(base);
@@ -612,8 +644,9 @@ const adopt = (issue: number, label: string, takenOver: ReadonlyArray<string>) =
612
644
  // queued the issue. What it puts on the issue, the claim ref and a branch it
613
645
  // created are markers, which the engine releases however the run ends; the
614
646
  // branch only while it holds no work, and not when a person takes over. The
615
- // branch starts from `base`'s head, the repo's base branch unless given, and
616
- // the claim marker records the base, which a run that resumes keeps. With
647
+ // branch starts from the head of `base`, the repo's base branch unless given,
648
+ // or of what it merged into once its pull request merged (landedBase), and
649
+ // the claim marker records that base, which a run that resumes keeps. With
617
650
  // `adopt`, an open pull request that already closes the issue is adopted
618
651
  // instead (see adopt): no branch is made, and `adopted` names it.
619
652
  export const claim = (
@@ -628,7 +661,7 @@ export const claim = (
628
661
  const label = yield* queueLabel(options);
629
662
  const branch = branchFor(issue);
630
663
  const item = Claims.issue(issue);
631
- const base = yield* baseOf(options);
664
+ const base = yield* landedBase(yield* baseOf(options));
632
665
  const baseSha = yield* baseHead(base);
633
666
  const claimed = yield* Claims.acquire(item);
634
667
 
@@ -1113,6 +1146,7 @@ export const askForClarification = (
1113
1146
  ].join("\n"),
1114
1147
  );
1115
1148
  yield* github.addLabel(issue, labels.needsClarification);
1149
+ yield* Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.askedQuestions);
1116
1150
  yield* dropInProgress(issue);
1117
1151
  yield* github.deleteBranch(branchFor(issue));
1118
1152
  yield* (yield* Worktree).remove(branchFor(issue));
@@ -1493,6 +1527,29 @@ export type HandOffOptions = {
1493
1527
  readonly adoptedBranch?: string;
1494
1528
  } & RepeatOptions;
1495
1529
 
1530
+ const handedOffAs = (options: { readonly draft?: boolean }): Phases.Phase => {
1531
+ if (options.draft === true) {
1532
+ return Phases.PHASES.pullRequest.draft;
1533
+ }
1534
+
1535
+ return Phases.PHASES.pullRequest.reviewAsked;
1536
+ };
1537
+
1538
+ // The phases a hand-off records: the pull request's, waiting for its first
1539
+ // review or, as a draft, for a person to mark it ready, and then the issue's,
1540
+ // whose progress goes on as the pull request's. In that order, so a crash
1541
+ // between the two leaves the pull request findable, and a replay of the
1542
+ // hand-off writes the issue's.
1543
+ export const recordHandOff = (
1544
+ issue: number,
1545
+ pullRequest: number,
1546
+ options: { readonly draft?: boolean },
1547
+ ) =>
1548
+ Effect.gen(function* () {
1549
+ yield* Phases.record(Phases.pullRequestItem(pullRequest), handedOffAs(options));
1550
+ yield* Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.handedOff);
1551
+ });
1552
+
1496
1553
  // Hands the green pull request to review: a review requested of one reviewer
1497
1554
  // from the pool (needs-review for a person without one) unless the options leave it off, and a closing comment
1498
1555
  // on the issue.
@@ -1532,6 +1589,7 @@ export const handOff = (
1532
1589
  }
1533
1590
 
1534
1591
  yield* dropInProgress(issue);
1592
+ yield* recordHandOff(issue, pullRequest.number, options);
1535
1593
 
1536
1594
  if (options.draft === true) {
1537
1595
  yield* github.comment(
@@ -1564,7 +1622,11 @@ export const adoptedOutcome = (adopted: Adopted): ImplementOutcome => ({
1564
1622
  // review: `ready`, or `timeout` once `timeout` passes. Either way the issue's
1565
1623
  // awaiting-ready label comes off.
1566
1624
  export const awaitReady = (issue: number, pullRequest: number, timeout: Duration.Input) =>
1567
- awaitSignal(["ready"], { id: `draft-${pullRequest}`, timeout }).pipe(
1625
+ activity(
1626
+ `awaiting-ready-${pullRequest}`,
1627
+ Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.awaitingReady),
1628
+ ).pipe(
1629
+ Effect.andThen(awaitSignal(["ready"], { id: `draft-${pullRequest}`, timeout })),
1568
1630
  Effect.tap(() =>
1569
1631
  activity(
1570
1632
  `ready-${pullRequest}`,
package/src/index.ts CHANGED
@@ -11,8 +11,10 @@ export * as Ci from "./ci.ts";
11
11
  export * as Compose from "./compose.ts";
12
12
  export * as Epic from "./epic.ts";
13
13
  export type * as EpicBlocks from "./epic-blocks.ts";
14
+ export * as Events from "./events.ts";
14
15
  export * as Hybrid from "./hybrid.ts";
15
16
  export * as Implement from "./implement.ts";
17
+ export * as Phases from "./phases.ts";
16
18
  export * as Plan from "./plan.ts";
17
19
  export * from "./prompt.ts";
18
20
  export * as Review from "./review.ts";