@chernabog/sdk 0.7.0 → 0.8.1

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,361 @@
1
+ // The settings the SDK's blocks read, as schemas a recipe includes in its own:
2
+ // `settings: Schema.Struct({ ...Settings.Ci.fields, promoteFrom: Schema.String })`.
3
+ // A repo sets them in .chernabog/config.yaml, once for every flow under
4
+ // `settings:`, or for one under `flows.<name>.settings`. Each block reads its
5
+ // own keys with core's Settings.read, so a recipe that leaves a block's
6
+ // schema out still runs it, on what config.yaml set.
7
+ //
8
+ // Until core's next major (ADR 0005), a setting the flow's settings leave
9
+ // out falls back to config.yaml's old key, which the binary still gives
10
+ // every flow as Repo's: `limits.ciRounds` for `ciRounds`, `labels` for
11
+ // `labels`, `baseBranch` for `base`, and so on.
12
+
13
+ import { type FlowLabel, Repo, type RepoSettings, Settings as CoreSettings } from "@chernabog/core";
14
+ import * as Duration from "effect/Duration";
15
+ import * as Effect from "effect/Effect";
16
+ import * as Option from "effect/Option";
17
+ import * as Record from "effect/Record";
18
+ import * as Schema from "effect/Schema";
19
+ import * as Struct from "effect/Struct";
20
+
21
+ export const FlowSettings = CoreSettings.FlowSettings;
22
+
23
+ export type FlowSettings = CoreSettings.FlowSettings;
24
+
25
+ export type SettingsSchema = CoreSettings.SettingsSchema;
26
+
27
+ // Decodes the flow's settings with `schema`: the flow's own, or a part of it.
28
+ export const read = CoreSettings.read;
29
+
30
+ const Strings = Schema.Array(Schema.String);
31
+
32
+ // A YAML null turns the setting off.
33
+ const Nullable = <S extends Schema.Constraint>(schema: S) =>
34
+ Schema.optionalKey(Schema.NullOr(schema));
35
+
36
+ const Count = (description: string) => Schema.optionalKey(Schema.Int.annotate({ description }));
37
+
38
+ const DURATION = /^(\d+(?:\.\d+)?)\s*(millis?|seconds?|minutes?|hours?|days?|weeks?)$/;
39
+
40
+ const UNIT_MILLIS: Readonly<Record<string, number>> = {
41
+ milli: 1,
42
+ second: 1000,
43
+ minute: 60_000,
44
+ hour: 3_600_000,
45
+ day: 86_400_000,
46
+ week: 604_800_000,
47
+ };
48
+
49
+ // "6 hours", "90 minutes": the durations config may name.
50
+ const parseDuration = (text: string) =>
51
+ Option.fromNullishOr(DURATION.exec(text.trim())).pipe(
52
+ Option.flatMap((match) =>
53
+ Option.map(Record.get(UNIT_MILLIS, match[2].replace(/s$/, "")), (millis) =>
54
+ Duration.millis(Number(match[1]) * millis),
55
+ ),
56
+ ),
57
+ );
58
+
59
+ const DurationText = (description: string) =>
60
+ Schema.optionalKey(
61
+ Schema.String.pipe(
62
+ Schema.check(
63
+ Schema.makeFilter(
64
+ (text: string) =>
65
+ Option.isSome(parseDuration(text)) || `"${text}" is not a duration, such as "6 hours"`,
66
+ ),
67
+ ),
68
+ ).annotate({ description }),
69
+ );
70
+
71
+ // The labels the SDK's issue-to-pull-request blocks put on issues and pull
72
+ // requests, by what each means.
73
+ export const LabelNames = Schema.Struct({
74
+ eligible: Schema.String,
75
+ inProgress: Schema.String,
76
+ needsReview: Schema.String,
77
+ changesRequested: Schema.String,
78
+ approved: Schema.String,
79
+ needsHuman: Schema.String,
80
+ needsClarification: Schema.String,
81
+ stale: Schema.String,
82
+ // The automated path: a pull request merges only when it carries this.
83
+ ship: Schema.String,
84
+ // The hybrid path, for people reading GitHub: a person started the work. No block decides anything from it.
85
+ hybrid: Schema.String,
86
+ });
87
+
88
+ export type LabelNames = typeof LabelNames.Type;
89
+
90
+ export const DEFAULT_LABEL_NAMES: LabelNames = {
91
+ eligible: "auto:eligible",
92
+ inProgress: "auto:in-progress",
93
+ needsReview: "auto:needs-review",
94
+ changesRequested: "auto:changes-requested",
95
+ approved: "auto:approved",
96
+ needsHuman: "auto:needs-human",
97
+ needsClarification: "auto:needs-clarification",
98
+ stale: "auto:stale",
99
+ ship: "auto:ship",
100
+ hybrid: "hybrid",
101
+ };
102
+
103
+ const name = Schema.optionalKey(Schema.String);
104
+
105
+ export const Labels = Schema.Struct({
106
+ labels: Schema.optionalKey(
107
+ Schema.Struct({
108
+ eligible: name,
109
+ inProgress: name,
110
+ needsReview: name,
111
+ changesRequested: name,
112
+ approved: name,
113
+ needsHuman: name,
114
+ needsClarification: name,
115
+ stale: name,
116
+ ship: name,
117
+ hybrid: name,
118
+ }).annotate({ description: "The label names the SDK's blocks use, by what each means." }),
119
+ ),
120
+ });
121
+
122
+ // The label names, each one the flow's settings give over the repo's.
123
+ export const labels = Effect.gen(function* () {
124
+ const repo = yield* Repo;
125
+ const own = yield* read(Labels);
126
+
127
+ return { ...DEFAULT_LABEL_NAMES, ...repo.labels, ...own.labels } satisfies LabelNames;
128
+ });
129
+
130
+ const LOOK = {
131
+ eligible: { color: "0e8a16", description: "Queued for an unattended run; removed on claim" },
132
+ inProgress: { color: "fbca04", description: "An unattended run owns this issue" },
133
+ needsReview: {
134
+ color: "1d76db",
135
+ description: "PR is open and green; waiting for a person to review it",
136
+ },
137
+ changesRequested: { color: "e99695", description: "Review comments posted; waiting for a push" },
138
+ approved: { color: "0e8a16", description: "Approved by an agent review; a person merges" },
139
+ needsHuman: {
140
+ color: "b60205",
141
+ description: "A loop cap or a rule stopped the run; a person takes over",
142
+ },
143
+ needsClarification: {
144
+ color: "d876e3",
145
+ description: "Questions are on the issue; answer, then requeue",
146
+ },
147
+ stale: { color: "7f8c8d", description: "No push before the staleness timeout" },
148
+ ship: {
149
+ color: "5319e7",
150
+ description: "The automated path: chernabog implements, and merges once a review approves",
151
+ },
152
+ hybrid: {
153
+ color: "bfd4f2",
154
+ description: "The hybrid path: a person worked on it with an agent; a person merges",
155
+ },
156
+ } satisfies Readonly<
157
+ Record<keyof LabelNames, { readonly color: string; readonly description: string }>
158
+ >;
159
+
160
+ // The label set, with the look `chernabog labels` gives each.
161
+ export const labelSet = (names: LabelNames): ReadonlyArray<FlowLabel> =>
162
+ Struct.keys(LOOK).map((key) => ({
163
+ name: names[key],
164
+ ...LOOK[key],
165
+ }));
166
+
167
+ // For a flow's `labels`: the label set under the names its settings give.
168
+ export const declaredLabels = Effect.map(labels, labelSet);
169
+
170
+ export const Base = Schema.Struct({
171
+ base: Schema.optionalKey(
172
+ Schema.String.annotate({
173
+ description:
174
+ "The branch the flow's work starts from and its pull requests target, such as develop in git flow. Unset: the repo's default branch.",
175
+ }),
176
+ ),
177
+ });
178
+
179
+ // The integration base: the branch new work starts from and merges into. It
180
+ // is the flow's to choose, never the branch .chernabog/ is read from, which
181
+ // is GitHub's default; a flow that leaves it out targets that default (or
182
+ // config.yaml's deprecated baseBranch).
183
+ export const base = Effect.gen(function* () {
184
+ const repo = yield* Repo;
185
+ const own = yield* read(Base);
186
+
187
+ return own.base ?? repo.baseBranch;
188
+ });
189
+
190
+ export const Ci = Schema.Struct({
191
+ ciRounds: Count("Pushes to fix red CI before a person takes over."),
192
+ ciTimeout: DurationText('How long CI may stay pending before a person looks, such as "2 hours".'),
193
+ ciGates: Schema.optionalKey(
194
+ Schema.Literals(["required", "every"]).annotate({
195
+ description:
196
+ "The checks that must pass: those the base branch requires (every check when it requires none, or GitHub won't say), or every check.",
197
+ }),
198
+ ),
199
+ ciOptionalFailures: Schema.optionalKey(
200
+ Schema.Literals(["hold", "ignore"]).annotate({
201
+ description:
202
+ "Whether a failing check that doesn't gate still makes CI red (hold), or is left alone (ignore).",
203
+ }),
204
+ ),
205
+ });
206
+
207
+ // The CI gate's policy, for Ci.verdict: required checks gate, and any
208
+ // failing check holds, unless the flow's settings say otherwise.
209
+ export const ciGate = Effect.map(read(Ci), (own) => ({
210
+ gates: own.ciGates ?? "required",
211
+ optionalFailures: own.ciOptionalFailures ?? "hold",
212
+ }));
213
+
214
+ export const ci = Effect.gen(function* () {
215
+ const repo = yield* Repo;
216
+ const own = yield* read(Ci);
217
+
218
+ return {
219
+ rounds: own.ciRounds ?? repo.limits.ciRounds,
220
+ timeout: Option.getOrElse(
221
+ Option.flatMap(Option.fromUndefinedOr(own.ciTimeout), parseDuration),
222
+ () => repo.limits.ciTimeout,
223
+ ),
224
+ };
225
+ });
226
+
227
+ export const LocalGate = Schema.Struct({
228
+ localGate: Schema.optionalKey(
229
+ Strings.annotate({
230
+ description: "Commands the change must pass before its pull request opens.",
231
+ }),
232
+ ),
233
+ localGateRounds: Count(
234
+ "Agent attempts to get the local gate passing before a person takes over.",
235
+ ),
236
+ install: Nullable(
237
+ Schema.String.annotate({
238
+ description: "Run in a fresh worktree before the agent starts. null for none.",
239
+ }),
240
+ ),
241
+ });
242
+
243
+ // A flow's install over the repo's; null for none.
244
+ const installOf = (own: typeof LocalGate.Type, repo: RepoSettings) =>
245
+ Option.match(Option.fromUndefinedOr(own.install), {
246
+ onNone: () => repo.install,
247
+ onSome: Option.fromNullOr,
248
+ });
249
+
250
+ export const localGate = Effect.gen(function* () {
251
+ const repo = yield* Repo;
252
+ const own = yield* read(LocalGate);
253
+
254
+ return {
255
+ commands: own.localGate ?? repo.localGate,
256
+ rounds: own.localGateRounds ?? repo.limits.localGateRounds,
257
+ install: installOf(own, repo),
258
+ };
259
+ });
260
+
261
+ export const Reviewers = Schema.Struct({
262
+ reviewers: Schema.optionalKey(
263
+ Strings.annotate({
264
+ description:
265
+ "The reviewer pool, by GitHub login: a pull request with green CI asks one of them at random to review it, never its author. Each needs write access, since the reviewer merges on the automated path.",
266
+ }),
267
+ ),
268
+ reviewRounds: Count("Re-reviews of one pull request before a person takes over."),
269
+ });
270
+
271
+ export const reviewers = Effect.gen(function* () {
272
+ const repo = yield* Repo;
273
+ const own = yield* read(Reviewers);
274
+
275
+ return {
276
+ pool: own.reviewers ?? repo.reviewers ?? [],
277
+ rounds: own.reviewRounds ?? repo.limits.reviewRounds,
278
+ };
279
+ });
280
+
281
+ export const Rules = Schema.Struct({
282
+ humanOnly: Schema.optionalKey(
283
+ Strings.annotate({
284
+ description:
285
+ "Decisions the agent must stop for and leave to a person, beyond the repo's and the machine's.",
286
+ }),
287
+ ),
288
+ humanOnlyPaths: Schema.optionalKey(
289
+ Strings.annotate({
290
+ description:
291
+ "Paths a change must not touch; one that does goes to a person instead of a pull request.",
292
+ }),
293
+ ),
294
+ notes: Schema.optionalKey(Strings.annotate({ description: "Repo facts the agent should know." })),
295
+ });
296
+
297
+ // The rules an agent works by. humanOnly adds to the repo's and the machine's,
298
+ // so a flow's settings never drop a decision someone left to a person.
299
+ export const rules = Effect.gen(function* () {
300
+ const repo = yield* Repo;
301
+ const own = yield* read(Rules);
302
+
303
+ return {
304
+ humanOnly: [...repo.humanOnly, ...(own.humanOnly ?? [])],
305
+ humanOnlyPaths: own.humanOnlyPaths ?? repo.humanOnlyPaths,
306
+ notes: own.notes ?? repo.notes,
307
+ };
308
+ });
309
+
310
+ export const Board = Schema.Struct({
311
+ board: Nullable(
312
+ Schema.Struct({
313
+ projectNumber: Schema.Int,
314
+ readyStatus: Schema.String,
315
+ inProgressStatus: Schema.String,
316
+ }).annotate({
317
+ description:
318
+ "The GitHub project board an issue moves across as it is claimed. null for none.",
319
+ }),
320
+ ),
321
+ });
322
+
323
+ export const board = Effect.gen(function* () {
324
+ const repo = yield* Repo;
325
+ const own = yield* read(Board);
326
+
327
+ return Option.match(Option.fromUndefinedOr(own.board), {
328
+ onNone: () => repo.board,
329
+ onSome: Option.fromNullOr,
330
+ });
331
+ });
332
+
333
+ export const Plans = Schema.Struct({
334
+ planNodes: Count("The most tasks one plan may hold, its verify node aside."),
335
+ planRounds: Count(
336
+ "Times the agent is asked to fix a plan that fails its checks before a person takes over.",
337
+ ),
338
+ });
339
+
340
+ export const plans = Effect.gen(function* () {
341
+ const repo = yield* Repo;
342
+ const own = yield* read(Plans);
343
+
344
+ return {
345
+ nodes: own.planNodes ?? repo.limits.planNodes,
346
+ rounds: own.planRounds ?? repo.limits.planRounds,
347
+ };
348
+ });
349
+
350
+ export const Stacks = Schema.Struct({
351
+ stackDepth: Count(
352
+ "The most layers one stack may hold before the run stops starting new ones and waits for the bottom to merge.",
353
+ ),
354
+ });
355
+
356
+ export const stackDepth = Effect.gen(function* () {
357
+ const repo = yield* Repo;
358
+ const own = yield* read(Stacks);
359
+
360
+ return own.stackDepth ?? repo.limits.stackDepth;
361
+ });