@chernabog/sdk 0.10.0 → 0.11.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.
@@ -0,0 +1,274 @@
1
+ // The hybrid path's blocks, which the human-initiated recipe composes. A
2
+ // person starts the flow with `chernabog start <issue>`, rather than a trigger
3
+ // finding its work, and plans and implements the issue with the agent in a
4
+ // session in front of them. `chernabog open-pr`, from that session, ends it;
5
+ // then the change is checked, pushed and opened as a pull request labelled
6
+ // hybrid, CI is waited on, and a reviewer from the pool is asked. Fixes for
7
+ // the local gate and for red CI go back to the person's session, and a person
8
+ // merges.
9
+ //
10
+ // Until the session ends, a failure fails the run or stops it as it is, as the
11
+ // recipe's does: a session the person closes fails the run, which lets the
12
+ // claim go and keeps the issue in progress for their next start. After it, a
13
+ // failure goes to a person.
14
+
15
+ import { NeedsHuman, NothingCommitted } from "@chernabog/core";
16
+ import * as Effect from "effect/Effect";
17
+ import * as Option from "effect/Option";
18
+
19
+ import {
20
+ BaseBranch,
21
+ BranchName,
22
+ Committed,
23
+ defineBlock,
24
+ type IssueNumber,
25
+ onBase,
26
+ type PullRequestNumber,
27
+ pullRequestRef,
28
+ Pushed,
29
+ type WorktreePath,
30
+ } from "./block.ts";
31
+ import * as Hybrid from "./hybrid.ts";
32
+ import * as Implement from "./implement.ts";
33
+ import * as Review from "./review.ts";
34
+ import * as Settings from "./settings.ts";
35
+
36
+ // The step names these share with the issue's blocks in blocks.ts, which a
37
+ // path can't take twice: claim, local-gate, push, open-pull-request, ci, hand-off.
38
+
39
+ // A branch with nothing on it past its base is told so in the words the recipe uses.
40
+ const committedNothing = <A, E, R>(effect: Effect.Effect<A, E | NothingCommitted, R>) =>
41
+ effect.pipe(
42
+ Effect.catchIf(
43
+ (error): error is NothingCommitted => error instanceof NothingCommitted,
44
+ (nothing) =>
45
+ Effect.fail(
46
+ new NeedsHuman({ reason: `nothing was committed on ${nothing.branch} before open-pr` }),
47
+ ),
48
+ ),
49
+ );
50
+
51
+ export const humanInitiatedBlocks = {
52
+ "hybrid.claim": defineBlock({
53
+ name: "hybrid.claim",
54
+ // Only these subjects' scopes let its claim go when the run ends.
55
+ suits: ["issue", "spec"],
56
+ about:
57
+ "Claims the issue a person started with chernabog start, so only this run works on it, and makes its branch, auto/issue-<n>, or takes up the one an earlier start left. It labels the issue auto:in-progress, takes it out of the unattended queues (auto:eligible and auto:ship), and settles its base. An issue another run holds skips the run, naming how to let it go; one an unattended run left a branch for is left to it. The claim goes when the run ends, however it ends, and a session the person closes keeps the issue in progress for their next start.",
58
+ inputKinds: { issue: "IssueNumber" },
59
+ outputKinds: { branch: "BranchName", base: "Option<BaseBranch>" },
60
+ outcomeKinds: {},
61
+ stepNames: ["claim"],
62
+ inputs: { issue: "required" },
63
+ run: (input: { readonly issue: IssueNumber }) =>
64
+ Hybrid.claim(input.issue).pipe(
65
+ Effect.map((claim) => ({
66
+ branch: BranchName(claim.branch),
67
+ base: Option.map(Option.fromUndefinedOr(claim.base), BaseBranch),
68
+ })),
69
+ ),
70
+ failures: { NeedsHuman: "told", Skip: "skip", StepFailed: "fail" },
71
+ outcomes: {},
72
+ mustRoute: [],
73
+ contributes: { settings: { ...Settings.Base.fields, ...Settings.Board.fields } },
74
+ }),
75
+
76
+ "hybrid.workWithPerson": defineBlock({
77
+ name: "hybrid.workWithPerson",
78
+ about:
79
+ "Opens a session with the person and the agent on the issue, in the worktree, from the human-initiated prompt (.chernabog/prompts/human-initiated.md, or the SDK's own). It needs Claude under a launcher, since a person is in it. When they're done, the agent drafts the pull request with chernabog open-pr --draft and asks the person; their Yes, or their own chernabog open-pr, ends the session with its title, body and summary. A session the person closes first fails the run. There is one session per issue, so starting the issue again picks it back up.",
80
+ inputKinds: {
81
+ issue: "IssueNumber",
82
+ worktree: "WorktreePath",
83
+ base: "Option<BaseBranch>: the base to build on, from hybrid.claim",
84
+ },
85
+ outputKinds: {
86
+ finished: "what open-pr recorded: the pull request's title and body, and a summary",
87
+ committed: "Committed: proof for hybrid.push",
88
+ },
89
+ outcomeKinds: {},
90
+ before: ["hybrid.localGate", "hybrid.push"],
91
+ stepNames: ["work-with-person"],
92
+ inputs: { issue: "required", worktree: "required", base: "required" },
93
+ run: (input: {
94
+ readonly issue: IssueNumber;
95
+ readonly worktree: WorktreePath;
96
+ readonly base: Option.Option<BaseBranch>;
97
+ }) =>
98
+ Hybrid.workWithPerson(input.issue, input.worktree, onBase(input.base)).pipe(
99
+ Effect.map((finished) => ({ finished, committed: new Committed({}) })),
100
+ ),
101
+ failures: { NeedsHuman: "told", NotFound: "skip", Skip: "skip", StepFailed: "fail" },
102
+ outcomes: {},
103
+ mustRoute: [],
104
+ contributes: { settings: Settings.Rules.fields },
105
+ }),
106
+
107
+ "hybrid.localGate": defineBlock({
108
+ name: "hybrid.localGate",
109
+ about:
110
+ "Runs the repo's local gate in the worktree, sending a failure back to the person's session to fix, up to localGateRounds.",
111
+ inputKinds: { issue: "IssueNumber", worktree: "WorktreePath" },
112
+ outputKinds: "nothing",
113
+ outcomeKinds: {},
114
+ before: ["hybrid.push", "hybrid.openPullRequest"],
115
+ stepNames: ["local-gate"],
116
+ inputs: { issue: "required", worktree: "required" },
117
+ run: (input: { readonly issue: IssueNumber; readonly worktree: WorktreePath }) =>
118
+ Effect.gen(function* () {
119
+ const session = yield* Hybrid.personSession(input.issue);
120
+
121
+ return yield* Implement.localGate(input.worktree, { session });
122
+ }),
123
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
124
+ outcomes: {},
125
+ mustRoute: [],
126
+ contributes: { settings: Settings.LocalGate.fields },
127
+ }),
128
+
129
+ "hybrid.push": defineBlock({
130
+ name: "hybrid.push",
131
+ about:
132
+ "Pushes the branch the person worked on. The person watched the change written, so it pushes one that touches humanOnlyPaths too; a person still merges it. A branch with nothing committed past its base goes to a person, as does a push the remote rejects, such as a change to .github/workflows/ with a token that lacks the workflow scope.",
133
+ inputKinds: {
134
+ worktree: "WorktreePath",
135
+ branch: "BranchName",
136
+ base: "Option<BaseBranch>",
137
+ committed: "Committed: from hybrid.workWithPerson",
138
+ },
139
+ outputKinds: { pushed: "Pushed: proof for hybrid.openPullRequest" },
140
+ outcomeKinds: {},
141
+ before: ["hybrid.openPullRequest"],
142
+ stepNames: ["push"],
143
+ inputs: { worktree: "required", branch: "required", base: "required", committed: "required" },
144
+ run: (input: {
145
+ readonly worktree: WorktreePath;
146
+ readonly branch: BranchName;
147
+ readonly base: Option.Option<BaseBranch>;
148
+ readonly committed: Committed;
149
+ }) =>
150
+ committedNothing(
151
+ Implement.push("push", input.worktree, input.branch, {
152
+ ...onBase(input.base),
153
+ withPerson: true,
154
+ }),
155
+ ).pipe(Effect.as({ pushed: new Pushed({}) })),
156
+ failures: { NeedsHuman: "person", PushRejected: "person", Skip: "skip", StepFailed: "person" },
157
+ outcomes: {},
158
+ mustRoute: [],
159
+ contributes: {},
160
+ }),
161
+
162
+ "hybrid.openPullRequest": defineBlock({
163
+ name: "hybrid.openPullRequest",
164
+ about:
165
+ "Opens the pull request for the pushed branch with the title and body open-pr recorded, or finds the one already open, and labels it hybrid, never auto:ship, so a person merges it.",
166
+ inputKinds: {
167
+ issue: "IssueNumber",
168
+ finished: "what open-pr recorded, from hybrid.workWithPerson",
169
+ base: "Option<BaseBranch>",
170
+ pushed: "Pushed: from hybrid.push",
171
+ },
172
+ outputKinds: { number: "PullRequestNumber", url: "its URL" },
173
+ outcomeKinds: {},
174
+ opens: ["hand-off"],
175
+ stepNames: ["open-pull-request"],
176
+ inputs: { issue: "required", finished: "required", base: "required", pushed: "required" },
177
+ run: (input: {
178
+ readonly issue: IssueNumber;
179
+ readonly finished: Hybrid.Finished;
180
+ readonly base: Option.Option<BaseBranch>;
181
+ readonly pushed: Pushed;
182
+ }) =>
183
+ Hybrid.openPullRequest(input.issue, input.finished, onBase(input.base)).pipe(
184
+ Effect.map(pullRequestRef),
185
+ ),
186
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
187
+ outcomes: {},
188
+ mustRoute: [],
189
+ contributes: {},
190
+ }),
191
+
192
+ "hybrid.waitForCi": defineBlock({
193
+ name: "hybrid.waitForCi",
194
+ about:
195
+ "Waits for CI on the pull request, sending red back to the person's session to fix and pushing the fix as hybrid.push does, up to ciRounds. CI still red after that, or still pending after ciTimeout, goes to a person.",
196
+ inputKinds: {
197
+ issue: "IssueNumber",
198
+ pr: "PullRequestNumber",
199
+ worktree: "WorktreePath",
200
+ branch: "BranchName",
201
+ base: "Option<BaseBranch>",
202
+ },
203
+ outputKinds: "nothing",
204
+ outcomeKinds: {},
205
+ before: ["hybrid.handOff"],
206
+ stepNames: ["ci"],
207
+ inputs: {
208
+ issue: "required",
209
+ pr: "required",
210
+ worktree: "required",
211
+ branch: "required",
212
+ base: "required",
213
+ },
214
+ run: (input: {
215
+ readonly issue: IssueNumber;
216
+ readonly pr: PullRequestNumber;
217
+ readonly worktree: WorktreePath;
218
+ readonly branch: BranchName;
219
+ readonly base: Option.Option<BaseBranch>;
220
+ }) =>
221
+ Effect.gen(function* () {
222
+ const session = yield* Hybrid.personSession(input.issue);
223
+
224
+ return yield* committedNothing(
225
+ Implement.waitForCi(input.pr, input.worktree, {
226
+ ...session,
227
+ branch: input.branch,
228
+ ...onBase(input.base),
229
+ }),
230
+ );
231
+ }),
232
+ failures: {
233
+ CiTimedOut: "person",
234
+ NeedsHuman: "person",
235
+ PushRejected: "person",
236
+ Skip: "skip",
237
+ StepFailed: "person",
238
+ },
239
+ outcomes: {},
240
+ mustRoute: [],
241
+ contributes: { settings: Settings.Ci.fields },
242
+ }),
243
+
244
+ "hybrid.handOff": defineBlock({
245
+ name: "hybrid.handOff",
246
+ about:
247
+ "Hands the pull request to review: leaves the session marker, so answering a review reopens the person's session, takes auto:in-progress off the issue and comments there with open-pr's summary, and asks one reviewer from the pool; a pull request closed meanwhile goes to a person. review, address-review and re-review take it from there, and a person merges.",
248
+ inputKinds: {
249
+ issue: "IssueNumber",
250
+ pr: "the pull request, from hybrid.openPullRequest",
251
+ finished: "what open-pr recorded, from hybrid.workWithPerson",
252
+ },
253
+ outputKinds: "a summary of the hand-off, for `end`'s summary",
254
+ outcomeKinds: {},
255
+ closes: ["hand-off"],
256
+ stepNames: ["hand-off"],
257
+ inputs: { issue: "required", pr: "required", finished: "required" },
258
+ run: (input: {
259
+ readonly issue: IssueNumber;
260
+ readonly pr: { readonly number: PullRequestNumber; readonly url: string };
261
+ readonly finished: Hybrid.Finished;
262
+ }) => Hybrid.handOff(input.issue, input.pr, input.finished),
263
+ failures: {
264
+ NeedsHuman: "person",
265
+ NotFound: "skip",
266
+ PullRequestClosed: "person",
267
+ Skip: "skip",
268
+ StepFailed: "person",
269
+ },
270
+ outcomes: {},
271
+ mustRoute: [],
272
+ contributes: { settings: Settings.Reviewers.fields, doctor: [Review.poolCheck] },
273
+ }),
274
+ };
package/src/implement.ts CHANGED
@@ -1241,7 +1241,11 @@ export const PullRequestRef = Schema.Struct({ number: Schema.Finite, url: Schema
1241
1241
 
1242
1242
  export type PullRequestRef = typeof PullRequestRef.Type;
1243
1243
 
1244
- const footer = (shipping: boolean) => {
1244
+ const footer = (shipping: boolean, draft: boolean) => {
1245
+ if (draft) {
1246
+ return "Opened by Chernabog as a draft for an unattended run. A person marks it ready for review, and a person merges.";
1247
+ }
1248
+
1245
1249
  if (shipping) {
1246
1250
  return "Opened by Chernabog for an unattended run, on the automated path: it merges once its review approves.";
1247
1251
  }
@@ -1258,15 +1262,42 @@ const closes = (issue: number, options: PartOfOptions) =>
1258
1262
  onSome: (epic) => `Closes #${issue}\nPart of #${epic}`,
1259
1263
  });
1260
1264
 
1265
+ // draft: open the pull request as a draft, which hand-off asks nobody to
1266
+ // review: a person marks it ready. False unless given.
1267
+ export type DraftOptions = { readonly draft?: boolean };
1268
+
1269
+ // What GitHub's REST API answers to a pull request it opened.
1270
+ const RestOpened = Schema.Struct({ number: Schema.Finite, html_url: Schema.String });
1271
+
1272
+ // Opens a draft through the REST API, which core's openPullRequest has no
1273
+ // draft for, so an SDK that opens one runs on any core it already does.
1274
+ const openDraft = (opening: {
1275
+ readonly head: string;
1276
+ readonly base: string;
1277
+ readonly title: string;
1278
+ readonly body: string;
1279
+ }) =>
1280
+ Effect.gen(function* () {
1281
+ const github = yield* GitHub;
1282
+ const repo = yield* Repo;
1283
+
1284
+ const opened = yield* github
1285
+ .request("POST", `/repos/${repo.slug}/pulls`, Option.some({ ...opening, draft: true }))
1286
+ .pipe(Effect.flatMap((json: Json) => Schema.decodeUnknownEffect(RestOpened)(json)));
1287
+
1288
+ return { number: opened.number, url: opened.html_url };
1289
+ });
1290
+
1261
1291
  // Opens the pull request for the branch, or finds the one already open. An
1262
1292
  // issue queued by ship (auto:ship) gives its pull request the label too, the
1263
1293
  // automated path, which merges once approved. It targets `base`, the repo's
1264
1294
  // base branch unless given. A task of an epic says so under its Closes line.
1265
- // The run names the pull request as a subject.
1295
+ // The run names the pull request as a subject. With draft, it opens as a
1296
+ // draft; one already open is kept as it is.
1266
1297
  export const openPullRequest = (
1267
1298
  issue: number,
1268
1299
  outcome: ImplementOutcome,
1269
- options: QueueOptions & BaseOptions & RepeatOptions & PartOfOptions = {},
1300
+ options: QueueOptions & BaseOptions & RepeatOptions & PartOfOptions & DraftOptions = {},
1270
1301
  ) =>
1271
1302
  activity(
1272
1303
  named(options, "open-pull-request"),
@@ -1282,15 +1313,26 @@ export const openPullRequest = (
1282
1313
  (pull) => pull.state === "open",
1283
1314
  );
1284
1315
 
1316
+ const draft = options.draft === true;
1317
+
1318
+ const opening = {
1319
+ head: branch,
1320
+ base,
1321
+ title: outcome.title,
1322
+ body: `${closes(issue, options)}\n\n${outcome.body}\n\n---\n${footer(shipping, draft)}`,
1323
+ };
1324
+
1325
+ const open = Effect.suspend(() => {
1326
+ if (draft) {
1327
+ return openDraft(opening);
1328
+ }
1329
+
1330
+ return github.openPullRequest(opening);
1331
+ });
1332
+
1285
1333
  const opened = yield* Option.match(existing, {
1286
1334
  onSome: Effect.succeed,
1287
- onNone: () =>
1288
- github.openPullRequest({
1289
- head: branch,
1290
- base,
1291
- title: outcome.title,
1292
- body: `${closes(issue, options)}\n\n${outcome.body}\n\n---\n${footer(shipping)}`,
1293
- }),
1335
+ onNone: () => open,
1294
1336
  });
1295
1337
 
1296
1338
  yield* Subjects.name(Claims.pullRequest(opened.number));
@@ -1443,8 +1485,11 @@ const askForReview = (pullRequest: number, options: HandOffOptions) => {
1443
1485
  // reviews the pull request itself says false. adoptedBranch: the pull request
1444
1486
  // is one claim adopted, on this branch, which no session of this run wrote.
1445
1487
  // `id` as RepeatOptions.
1488
+ // draft: the pull request is a draft, which the issue is told a person marks
1489
+ // ready; the flow says needsReview false for it.
1446
1490
  export type HandOffOptions = {
1447
1491
  readonly needsReview: boolean;
1492
+ readonly draft?: boolean;
1448
1493
  readonly adoptedBranch?: string;
1449
1494
  } & RepeatOptions;
1450
1495
 
@@ -1487,6 +1532,16 @@ export const handOff = (
1487
1532
  }
1488
1533
 
1489
1534
  yield* dropInProgress(issue);
1535
+
1536
+ if (options.draft === true) {
1537
+ yield* github.comment(
1538
+ issue,
1539
+ `Draft pull request opened: ${pullRequest.url}. A person marks it ready for review.\n\n${outcome.summary}`,
1540
+ );
1541
+
1542
+ return `#${issue}: ${pullRequest.url} is a draft, for a person to mark ready`;
1543
+ }
1544
+
1490
1545
  yield* github.comment(
1491
1546
  issue,
1492
1547
  `Pull request ready for review: ${pullRequest.url}\n\n${outcome.summary}`,
package/src/index.ts CHANGED
@@ -6,8 +6,11 @@ import * as PullRequestSteps from "./pull-request.ts";
6
6
  // @chernabog/sdk: the blocks a recipe is written from, over core's ports and
7
7
  // nothing else, and core itself, so a flow imports from one package. A repo
8
8
  // pins its own version; the binary only provides core.
9
+ export * as Blocks from "./blocks.ts";
9
10
  export * as Ci from "./ci.ts";
11
+ export * as Compose from "./compose.ts";
10
12
  export * as Epic from "./epic.ts";
13
+ export type * as EpicBlocks from "./epic-blocks.ts";
11
14
  export * as Hybrid from "./hybrid.ts";
12
15
  export * as Implement from "./implement.ts";
13
16
  export * as Plan from "./plan.ts";