@chernabog/sdk 0.4.0 → 0.7.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/README.md +39 -29
- package/package.json +1 -1
- package/src/claims.ts +169 -0
- package/src/comment.ts +6 -6
- package/src/default-prompts.ts +52 -0
- package/src/errors.ts +209 -20
- package/src/flow.ts +227 -62
- package/src/hybrid.ts +308 -0
- package/src/implement.ts +477 -191
- package/src/index.ts +17 -14
- package/src/issue.ts +2 -2
- package/src/json.ts +7 -4
- package/src/markers.ts +73 -16
- package/src/paths.ts +18 -10
- package/src/plan.ts +762 -0
- package/src/prompt.ts +76 -24
- package/src/pull-request.ts +254 -55
- package/src/review.ts +406 -301
- package/src/roles.ts +15 -8
- package/src/services.ts +239 -51
- package/src/stage.ts +4 -4
package/src/flow.ts
CHANGED
|
@@ -4,23 +4,44 @@
|
|
|
4
4
|
// the last completed one. Side effects belong inside activities, never in the
|
|
5
5
|
// workflow body, because the body runs again on every replay.
|
|
6
6
|
|
|
7
|
-
import * as Context from
|
|
8
|
-
import * as Duration from
|
|
9
|
-
import * as Effect from
|
|
10
|
-
import type * as FileSystem from
|
|
11
|
-
import * as Option from
|
|
12
|
-
import * as Predicate from
|
|
13
|
-
import type * as ChildProcessSpawner from
|
|
14
|
-
import * as Schema from
|
|
15
|
-
import type * as Scope from
|
|
16
|
-
import * as Activity from
|
|
17
|
-
import * as DurableClock from
|
|
18
|
-
import * as DurableDeferred from
|
|
19
|
-
import type * as WorkflowEngine from
|
|
20
|
-
|
|
21
|
-
import {
|
|
22
|
-
|
|
23
|
-
|
|
7
|
+
import * as Context from "effect/Context";
|
|
8
|
+
import * as Duration from "effect/Duration";
|
|
9
|
+
import * as Effect from "effect/Effect";
|
|
10
|
+
import type * as FileSystem from "effect/FileSystem";
|
|
11
|
+
import * as Option from "effect/Option";
|
|
12
|
+
import * as Predicate from "effect/Predicate";
|
|
13
|
+
import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
|
|
14
|
+
import * as Schema from "effect/Schema";
|
|
15
|
+
import type * as Scope from "effect/Scope";
|
|
16
|
+
import * as Activity from "effect/workflow/Activity";
|
|
17
|
+
import * as DurableClock from "effect/workflow/DurableClock";
|
|
18
|
+
import * as DurableDeferred from "effect/workflow/DurableDeferred";
|
|
19
|
+
import type * as WorkflowEngine from "effect/workflow/WorkflowEngine";
|
|
20
|
+
|
|
21
|
+
import {
|
|
22
|
+
AgentError,
|
|
23
|
+
GitError,
|
|
24
|
+
GitHubError,
|
|
25
|
+
NeedsHuman,
|
|
26
|
+
type ReportedError,
|
|
27
|
+
Skip,
|
|
28
|
+
StepFailed,
|
|
29
|
+
UsageError,
|
|
30
|
+
WorkError,
|
|
31
|
+
} from "./errors.ts";
|
|
32
|
+
import type { Json } from "./json.ts";
|
|
33
|
+
import {
|
|
34
|
+
type Agent,
|
|
35
|
+
type Git,
|
|
36
|
+
type GitHub,
|
|
37
|
+
type Repo,
|
|
38
|
+
type ReviewerSeat,
|
|
39
|
+
type Run,
|
|
40
|
+
RunLog,
|
|
41
|
+
type Usage,
|
|
42
|
+
type WorkItem,
|
|
43
|
+
type Worktree,
|
|
44
|
+
} from "./services.ts";
|
|
24
45
|
|
|
25
46
|
// Runs a step from .chernabog/stages/ in its own process. Provided by Chernabog.
|
|
26
47
|
export class StepRunner extends Context.Service<
|
|
@@ -28,7 +49,7 @@ export class StepRunner extends Context.Service<
|
|
|
28
49
|
{
|
|
29
50
|
run(name: string, input: Json): Effect.Effect<Json, Skip | StepFailed>;
|
|
30
51
|
}
|
|
31
|
-
>()(
|
|
52
|
+
>()("@chernabog/sdk/StepRunner") {}
|
|
32
53
|
|
|
33
54
|
// Records that a run waits on a signal, so the next tick's trigger can wake it. Provided by Chernabog.
|
|
34
55
|
export class Signals extends Context.Service<
|
|
@@ -36,9 +57,19 @@ export class Signals extends Context.Service<
|
|
|
36
57
|
{
|
|
37
58
|
register(signal: string, deferred: string, token: string): Effect.Effect<void>;
|
|
38
59
|
}
|
|
39
|
-
>()(
|
|
60
|
+
>()("@chernabog/sdk/Signals") {}
|
|
40
61
|
|
|
41
|
-
export type TriggerServices =
|
|
62
|
+
export type TriggerServices =
|
|
63
|
+
| Repo
|
|
64
|
+
| GitHub
|
|
65
|
+
| Git
|
|
66
|
+
| Worktree
|
|
67
|
+
| Usage
|
|
68
|
+
| Agent
|
|
69
|
+
| ReviewerSeat
|
|
70
|
+
| RunLog
|
|
71
|
+
| FileSystem.FileSystem
|
|
72
|
+
| ChildProcessSpawner.ChildProcessSpawner;
|
|
42
73
|
|
|
43
74
|
export type WorkflowServices =
|
|
44
75
|
| TriggerServices
|
|
@@ -49,92 +80,213 @@ export type WorkflowServices =
|
|
|
49
80
|
| WorkflowEngine.WorkflowInstance
|
|
50
81
|
| Scope.Scope;
|
|
51
82
|
|
|
83
|
+
// What a flow's trigger, gate and workflow may fail with: the flow's own
|
|
84
|
+
// outcomes. Any other error must be handled, or mapped to one of these, before
|
|
85
|
+
// the flow compiles: a work error such as PushRejected by deciding what it
|
|
86
|
+
// means for the work, and an error the flow can only report with `reportAs`.
|
|
52
87
|
export type FlowError = Skip | NeedsHuman | StepFailed;
|
|
53
88
|
|
|
54
|
-
// What a flow's trigger, gate and workflow may fail with: anything, which the engine reports by its message.
|
|
55
|
-
export type FlowFailure = { readonly _tag: string } | Error;
|
|
56
|
-
|
|
57
89
|
// A label a flow triggers on or sets beyond the repo's own, such as auto:ship. `chernabog labels` creates it.
|
|
58
|
-
export type FlowLabel = {
|
|
90
|
+
export type FlowLabel = {
|
|
91
|
+
readonly name: string;
|
|
92
|
+
readonly color?: string;
|
|
93
|
+
readonly description?: string;
|
|
94
|
+
};
|
|
59
95
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
96
|
+
// The work item for a key a person names: the issue `chernabog start` hands
|
|
97
|
+
// over, say. None when there is no such item.
|
|
98
|
+
export type ItemLookup = (
|
|
99
|
+
key: string,
|
|
100
|
+
) => Effect.Effect<Option.Option<WorkItem>, FlowError, TriggerServices>;
|
|
101
|
+
|
|
102
|
+
// What every flow has, whether a trigger finds its work or a person names it.
|
|
103
|
+
type FlowCommon = {
|
|
63
104
|
// Checked before each run starts; fail with Skip to hold the run back, such as on usage.
|
|
64
|
-
readonly gate?: Effect.Effect<void,
|
|
105
|
+
readonly gate?: Effect.Effect<void, FlowError, TriggerServices>;
|
|
65
106
|
// Runs of this flow in one repo at once. Defaults to 1; machine limits still apply.
|
|
66
107
|
readonly concurrency?: number;
|
|
67
|
-
// A cron schedule for the trigger, overriding the repo's default.
|
|
68
|
-
readonly schedule?: string;
|
|
69
108
|
// Labels of the flow's own, for `chernabog labels` to create.
|
|
70
109
|
readonly labels?: ReadonlyArray<FlowLabel>;
|
|
110
|
+
// Whether the trigger finds only the work of the persona it runs as, as
|
|
111
|
+
// review's does by its review requests, so several personas can run the
|
|
112
|
+
// flow without assignee or reviewRequested to tell them apart.
|
|
113
|
+
readonly ownWork?: boolean;
|
|
71
114
|
// The durable work for one item. Its result, if a string, is the run's summary.
|
|
72
|
-
readonly workflow: (item: WorkItem) => Effect.Effect<string | void,
|
|
115
|
+
readonly workflow: (item: WorkItem) => Effect.Effect<string | void, FlowError, WorkflowServices>;
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
// A flow whose trigger finds its work, on a schedule.
|
|
119
|
+
export type TriggeredFlow = FlowCommon & {
|
|
120
|
+
// The work items in the state this flow acts on, such as issues labelled auto:eligible.
|
|
121
|
+
readonly trigger: Effect.Effect<ReadonlyArray<WorkItem>, FlowError, TriggerServices>;
|
|
122
|
+
// A cron schedule for the trigger, overriding the repo's default.
|
|
123
|
+
readonly schedule?: string;
|
|
124
|
+
// The work item for a key a person names, when the trigger doesn't report it.
|
|
125
|
+
readonly item?: ItemLookup;
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
// A flow with no trigger: nothing finds its work, and it runs only when a
|
|
129
|
+
// person names an item, as `chernabog start <issue>` does. It has no schedule.
|
|
130
|
+
export type ManualFlow = FlowCommon & {
|
|
131
|
+
readonly trigger?: never;
|
|
132
|
+
readonly schedule?: never;
|
|
133
|
+
readonly item: ItemLookup;
|
|
73
134
|
};
|
|
74
135
|
|
|
136
|
+
export type Flow = TriggeredFlow | ManualFlow;
|
|
137
|
+
|
|
75
138
|
export const defineFlow = (flow: Flow): Flow => flow;
|
|
76
139
|
|
|
140
|
+
// Whether a person starts each of the flow's runs, by naming its work.
|
|
141
|
+
export const isManual = (flow: Flow): flow is ManualFlow => !Effect.isEffect(flow.trigger);
|
|
142
|
+
|
|
143
|
+
// What the flow's trigger reports; nothing, for a manual flow.
|
|
144
|
+
export const triggerOf = (flow: Flow): TriggeredFlow["trigger"] => {
|
|
145
|
+
if (isManual(flow)) {
|
|
146
|
+
return Effect.succeed([]);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
return flow.trigger;
|
|
150
|
+
};
|
|
151
|
+
|
|
77
152
|
const FlowErrorSchema = Schema.Union([Skip, NeedsHuman, StepFailed]);
|
|
78
|
-
|
|
153
|
+
|
|
154
|
+
// What an activity may fail with, as its journal stores it: the flow's outcomes and the work's errors.
|
|
155
|
+
const ActivityError = Schema.Union([...FlowErrorSchema.members, ...WorkError.members]);
|
|
156
|
+
const isActivityError = Schema.is(ActivityError);
|
|
79
157
|
|
|
80
158
|
// An error's message, whatever shape it came in.
|
|
81
159
|
export const describeError = <E>(error: E): string => {
|
|
82
|
-
if (Predicate.hasProperty(error,
|
|
160
|
+
if (Predicate.hasProperty(error, "step") && Predicate.hasProperty(error, "message")) {
|
|
161
|
+
return `${String(error.step)}: ${String(error.message)}`;
|
|
162
|
+
}
|
|
83
163
|
|
|
84
|
-
if (Predicate.hasProperty(error,
|
|
164
|
+
if (Predicate.hasProperty(error, "message") && Predicate.isString(error.message)) {
|
|
165
|
+
return error.message;
|
|
166
|
+
}
|
|
85
167
|
|
|
86
|
-
if (Predicate.hasProperty(error,
|
|
168
|
+
if (Predicate.hasProperty(error, "reason") && Predicate.isString(error.reason)) {
|
|
169
|
+
return error.reason;
|
|
170
|
+
}
|
|
87
171
|
|
|
88
172
|
return String(error);
|
|
89
173
|
};
|
|
90
174
|
|
|
91
|
-
// Keeps the
|
|
92
|
-
const
|
|
175
|
+
// Keeps the flow's outcomes and the work's errors, and names the activity in any other failure.
|
|
176
|
+
const toActivityError =
|
|
93
177
|
(name: string) =>
|
|
94
|
-
<E>(error: E): FlowError => {
|
|
95
|
-
if (
|
|
178
|
+
<E>(error: E): FlowError | WorkError => {
|
|
179
|
+
if (isActivityError(error)) {
|
|
180
|
+
return error;
|
|
181
|
+
}
|
|
96
182
|
|
|
97
183
|
return new StepFailed({ step: name, message: describeError(error) });
|
|
98
184
|
};
|
|
99
185
|
|
|
100
|
-
const
|
|
101
|
-
|
|
186
|
+
const isReportedError = Schema.is(Schema.Union([GitHubError, GitError, AgentError, UsageError]));
|
|
187
|
+
|
|
188
|
+
const isReported = <E>(error: E): error is Extract<E, ReportedError> => isReportedError(error);
|
|
189
|
+
|
|
190
|
+
// Turns the errors a flow can only report (GitHubError, GitError, AgentError,
|
|
191
|
+
// UsageError) into StepFailed, named for `step`, and keeps every other error
|
|
192
|
+
// for the flow to handle. For a trigger, or work outside an activity, which
|
|
193
|
+
// does the same for its own.
|
|
194
|
+
export const reportAs =
|
|
195
|
+
(step: string) =>
|
|
196
|
+
<A, E, R>(effect: Effect.Effect<A, E, R>) =>
|
|
197
|
+
Effect.catchIf(
|
|
198
|
+
effect,
|
|
199
|
+
isReported,
|
|
200
|
+
(error) => Effect.fail(new StepFailed({ step, message: error.message })),
|
|
201
|
+
(other) => Effect.fail(other),
|
|
202
|
+
);
|
|
203
|
+
|
|
204
|
+
const withRunLog = (use: (log: RunLog["Service"]) => Effect.Effect<void>) =>
|
|
205
|
+
Effect.serviceOption(RunLog).pipe(
|
|
206
|
+
Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: use })),
|
|
207
|
+
);
|
|
208
|
+
|
|
209
|
+
// An activity's journal holds any of the flow's outcomes and work errors, but
|
|
210
|
+
// an activity only ever fails with the outcomes and the work errors its own
|
|
211
|
+
// execute raised: toActivityError keeps no others, and a replay reads back
|
|
212
|
+
// what it kept. So a failure that is an activity error is one of E's.
|
|
213
|
+
const raisedBy =
|
|
214
|
+
<E>() =>
|
|
215
|
+
(error: FlowError | WorkError): error is FlowError | Extract<E, WorkError> =>
|
|
216
|
+
isActivityError(error);
|
|
217
|
+
|
|
218
|
+
const narrowed =
|
|
219
|
+
<E>(name: string) =>
|
|
220
|
+
<A, R>(effect: Effect.Effect<A, FlowError | WorkError, R>) =>
|
|
221
|
+
Effect.catchIf(effect, raisedBy<E>(), Effect.fail, (other) =>
|
|
222
|
+
Effect.fail(new StepFailed({ step: name, message: describeError(other) })),
|
|
223
|
+
);
|
|
224
|
+
|
|
225
|
+
// The step an activity is running, for what it calls to know by name: the
|
|
226
|
+
// Agent service gives it to the adapter, so a rehearsal's stand-ins are
|
|
227
|
+
// keyed by step. None outside an activity.
|
|
228
|
+
export const CurrentActivity = Context.Reference<Option.Option<string>>(
|
|
229
|
+
"@chernabog/sdk/CurrentActivity",
|
|
230
|
+
{
|
|
231
|
+
defaultValue: () => Option.none(),
|
|
232
|
+
},
|
|
233
|
+
);
|
|
102
234
|
|
|
103
235
|
// One durable step of a workflow. It runs once; its result is saved, and a
|
|
104
236
|
// replay returns the saved result. Names must be unique within a run, so a
|
|
105
237
|
// step inside a loop carries its round: `fix-ci-2`. `success` is the result's
|
|
106
238
|
// schema, which the journal stores it with; leave it out for a step that
|
|
107
|
-
// returns nothing.
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
239
|
+
// returns nothing. It fails with the flow's outcomes and the work's errors
|
|
240
|
+
// it raised, which the flow handles; any other failure is StepFailed.
|
|
241
|
+
export const activity = <S extends Schema.Constraint = typeof Schema.Void, E = never, R = never>(
|
|
242
|
+
name: string,
|
|
243
|
+
execute: Effect.Effect<S["Type"], E, R>,
|
|
244
|
+
success?: S,
|
|
245
|
+
) =>
|
|
246
|
+
narrowed<E>(name)(
|
|
247
|
+
Activity.make({
|
|
248
|
+
name,
|
|
249
|
+
success,
|
|
250
|
+
error: ActivityError,
|
|
251
|
+
execute: withRunLog((log) => log.step(name)).pipe(
|
|
252
|
+
Effect.andThen(Effect.provideService(execute, CurrentActivity, Option.some(name))),
|
|
253
|
+
Effect.ensuring(withRunLog((log) => log.stepDone(name))),
|
|
254
|
+
Effect.mapError(toActivityError(name)),
|
|
255
|
+
),
|
|
256
|
+
}),
|
|
257
|
+
);
|
|
119
258
|
|
|
120
259
|
// Runs .chernabog/stages/<name>.ts (or an executable <name>) in a child
|
|
121
260
|
// process, checks its output against `output`, and saves the result. `id`
|
|
122
261
|
// tells apart two runs of one step in a run.
|
|
123
|
-
export const step = <A>(
|
|
262
|
+
export const step = <A>(
|
|
263
|
+
name: string,
|
|
264
|
+
input: Json,
|
|
265
|
+
output: Schema.Codec<A, Json>,
|
|
266
|
+
id: Option.Option<string> = Option.none(),
|
|
267
|
+
) =>
|
|
124
268
|
activity(
|
|
125
269
|
Option.match(id, { onNone: () => name, onSome: (suffix) => `${name}#${suffix}` }),
|
|
126
270
|
StepRunner.use((runner) => runner.run(name, input)).pipe(
|
|
127
|
-
Effect.flatMap((raw) =>
|
|
271
|
+
Effect.flatMap((raw) =>
|
|
272
|
+
Schema.decodeEffect(output)(raw).pipe(
|
|
273
|
+
Effect.mapError(
|
|
274
|
+
(issue) => new StepFailed({ step: name, message: `output: ${issue.message}` }),
|
|
275
|
+
),
|
|
276
|
+
),
|
|
277
|
+
),
|
|
128
278
|
),
|
|
129
279
|
output,
|
|
130
280
|
);
|
|
131
281
|
|
|
132
282
|
// A durable pause: it survives restarts, and a timer that came due while the
|
|
133
283
|
// daemon was down fires as soon as it is back.
|
|
134
|
-
export const sleep = (name: string, duration: Duration.Input) =>
|
|
284
|
+
export const sleep = (name: string, duration: Duration.Input) =>
|
|
285
|
+
DurableClock.sleep({ name, duration, inMemoryThreshold: Duration.zero });
|
|
135
286
|
|
|
136
287
|
// The durable deferred behind one wait, by name. Chernabog completes it with `true` when the signal comes.
|
|
137
|
-
export const signalDeferred = (name: string) =>
|
|
288
|
+
export const signalDeferred = (name: string) =>
|
|
289
|
+
DurableDeferred.make(name, { success: Schema.Literal(true) });
|
|
138
290
|
|
|
139
291
|
export type Wait = { readonly id: string; readonly timeout: Duration.Input };
|
|
140
292
|
|
|
@@ -144,17 +296,30 @@ export type Wait = { readonly id: string; readonly timeout: Duration.Input };
|
|
|
144
296
|
// `awaitSignal(["pushed", "closed"], { id: "round-2", timeout: "6 hours" })`.
|
|
145
297
|
export const awaitSignal = (signals: ReadonlyArray<string>, wait: Wait) =>
|
|
146
298
|
Effect.gen(function* () {
|
|
147
|
-
const waits = signals.map((signal) => ({
|
|
299
|
+
const waits = signals.map((signal) => ({
|
|
300
|
+
signal,
|
|
301
|
+
deferred: signalDeferred(`${signal}:${wait.id}`),
|
|
302
|
+
}));
|
|
148
303
|
|
|
149
304
|
for (const pending of waits) {
|
|
150
305
|
const token = yield* DurableDeferred.token(pending.deferred);
|
|
151
|
-
yield* activity(
|
|
306
|
+
yield* activity(
|
|
307
|
+
`await-${pending.deferred.name}`,
|
|
308
|
+
Signals.use((registry) => registry.register(pending.signal, pending.deferred.name, token)),
|
|
309
|
+
);
|
|
152
310
|
}
|
|
153
311
|
|
|
154
312
|
const [first, ...rest] = [
|
|
155
|
-
...waits.map((pending) =>
|
|
156
|
-
|
|
313
|
+
...waits.map((pending) =>
|
|
314
|
+
DurableDeferred.await(pending.deferred).pipe(Effect.as(pending.signal)),
|
|
315
|
+
),
|
|
316
|
+
sleep(`timeout:${wait.id}`, wait.timeout).pipe(Effect.as("timeout")),
|
|
157
317
|
];
|
|
158
318
|
|
|
159
|
-
return yield* DurableDeferred.raceAll({
|
|
319
|
+
return yield* DurableDeferred.raceAll({
|
|
320
|
+
name: `race:${wait.id}`,
|
|
321
|
+
success: Schema.String,
|
|
322
|
+
error: Schema.Never,
|
|
323
|
+
effects: [first, ...rest],
|
|
324
|
+
});
|
|
160
325
|
});
|