@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/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 '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 { NeedsHuman, Skip, StepFailed } from './errors.ts';
22
- import type { Json } from './json.ts';
23
- import { type Agent, type Git, type GitHub, type Repo, type Run, RunLog, type Usage, type WorkItem, type Worktree } from './services.ts';
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
- >()('@chernabog/sdk/StepRunner') {}
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
- >()('@chernabog/sdk/Signals') {}
60
+ >()("@chernabog/sdk/Signals") {}
40
61
 
41
- export type TriggerServices = Repo | GitHub | Git | Worktree | Usage | Agent | RunLog | FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner;
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 = { readonly name: string; readonly color?: string; readonly description?: string };
90
+ export type FlowLabel = {
91
+ readonly name: string;
92
+ readonly color?: string;
93
+ readonly description?: string;
94
+ };
59
95
 
60
- export type Flow = {
61
- // The work items in the state this flow acts on, such as issues labelled auto:eligible.
62
- readonly trigger: Effect.Effect<ReadonlyArray<WorkItem>, FlowFailure, TriggerServices>;
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, FlowFailure, TriggerServices>;
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, FlowFailure, WorkflowServices>;
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
- const isFlowError = Schema.is(FlowErrorSchema);
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, 'step') && Predicate.hasProperty(error, 'message')) return `${String(error.step)}: ${String(error.message)}`;
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, 'message') && Predicate.isString(error.message)) return error.message;
164
+ if (Predicate.hasProperty(error, "message") && Predicate.isString(error.message)) {
165
+ return error.message;
166
+ }
85
167
 
86
- if (Predicate.hasProperty(error, 'reason') && Predicate.isString(error.reason)) return error.reason;
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 SDK's own outcomes, and names the activity in any other failure.
92
- const toFlowError =
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 (isFlowError(error)) return error;
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 withRunLog = (use: (log: RunLog['Service']) => Effect.Effect<void>) =>
101
- Effect.serviceOption(RunLog).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: use })));
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
- export const activity = <S extends Schema.Constraint = typeof Schema.Void, E = never, R = never>(name: string, execute: Effect.Effect<S['Type'], E, R>, success?: S) =>
109
- Activity.make({
110
- name,
111
- success,
112
- error: FlowErrorSchema,
113
- execute: withRunLog((log) => log.step(name)).pipe(
114
- Effect.andThen(execute),
115
- Effect.ensuring(withRunLog((log) => log.stepDone(name))),
116
- Effect.mapError(toFlowError(name)),
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>(name: string, input: Json, output: Schema.Codec<A, Json>, id: Option.Option<string> = Option.none()) =>
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) => Schema.decodeEffect(output)(raw).pipe(Effect.mapError((issue) => new StepFailed({ step: name, message: `output: ${issue.message}` })))),
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) => DurableClock.sleep({ name, duration, inMemoryThreshold: Duration.zero });
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) => DurableDeferred.make(name, { success: Schema.Literal(true) });
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) => ({ signal, deferred: signalDeferred(`${signal}:${wait.id}`) }));
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(`await-${pending.deferred.name}`, Signals.use((registry) => registry.register(pending.signal, pending.deferred.name, token)));
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) => DurableDeferred.await(pending.deferred).pipe(Effect.as(pending.signal))),
156
- sleep(`timeout:${wait.id}`, wait.timeout).pipe(Effect.as('timeout')),
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({ name: `race:${wait.id}`, success: Schema.String, error: Schema.Never, effects: [first, ...rest] });
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
  });