@chernabog/sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @chernabog/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The services and helpers for writing Chernabog flows and steps. At runtime the `chernabog` binary supplies its own copy of this package and of `effect`, so a repo needs them only as devDependencies, for types.
+
+## Flows
+
+```ts
+import { defineFlow, Implement, step } from '@chernabog/sdk';
+import { Effect, Schema } from 'effect';
+
+export default defineFlow({
+  trigger: Implement.trigger, // the work items to act on
+  gate: Implement.gate,       // checked before each run starts; fail with Skip to hold it back
+  concurrency: 1,
+  workflow: (item) =>
+    Effect.gen(function* () {
+      const issue = Implement.issueOf(item);
+      const { branch } = yield* Implement.claim(issue);
+      const checked = yield* step('check-scope', { issue }, { output: Schema.Struct({ ok: Schema.Boolean }) });
+      // ...
+    }),
+});
+```
+
+| Helper | What it does |
+| --- | --- |
+| `activity(name, effect, { success })` | One durable step. It runs once and its result is saved; a replay returns the saved result. Names are unique within a run, so a step in a loop carries its round: `fix-ci-2`. |
+| `step(name, input, { output })` | Runs `.chernabog/stages/<name>` in its own process, as an activity. |
+| `sleep(name, duration)` | A durable pause that survives restarts. |
+| `awaitSignal(signals, { id, timeout })` | Waits for one of the signals (which the trigger reports in `WorkItem.signals`) or the timeout, whichever comes first, and says which. A trigger can report an item with `wakeOnly` to wake a waiting run without starting a new one. |
+| `renderPrompt(name, values)` | Fills `.chernabog/prompts/<name>.md`. |
+| `Skip`, `NeedsHuman` | End a run cleanly, or hand its item to a person. |
+
+`Implement` and `Review` hold the building blocks of the default flows, each an activity a flow can reorder, leave out or wrap.
+
+Side effects belong inside activities or steps, never in the workflow body, which runs again on every replay.
+
+## Steps
+
+```ts
+// .chernabog/stages/find-work.ts
+import { defineStage, GitHub, Skip } from '@chernabog/sdk';
+import { Effect, Schema } from 'effect';
+
+export default defineStage({
+  name: 'find-work',
+  input: Schema.Struct({}),
+  output: Schema.Struct({ issue: Schema.Number }),
+  run: () =>
+    Effect.gen(function* () {
+      const issue = yield* (yield* GitHub).oldestQueued;
+      if (issue === undefined) return yield* new Skip({ reason: 'nothing queued' });
+      return { issue };
+    }),
+});
+```
+
+## Services
+
+| Service | Covers |
+| --- | --- |
+| `Repo` | The repo's merged settings: slug, base branch, labels, limits, gates, notes |
+| `Run` | The run: flow, run id and work item |
+| `GitHub` | Queued issues, claims, labels, comments, branches, pull requests, CI state |
+| `Agent` | Starting and resuming agent sessions through an adapter |
+| `Git`, `Worktree` | Commits ahead, changed files, pushes; one worktree per branch |
+| `Usage` | The account check and the usage gate |
+| `RunLog` | The run's log |
+
+Each service is a layer, so a team can replace one with its own implementation, and tests can use fakes.

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@chernabog/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Services and helpers for writing Chernabog flows and steps",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dataquail/chernabog.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "effect": "4.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,33 @@
+import * as Schema from 'effect/Schema';
+
+// Ends a run cleanly: nothing to do, or a gate said not now. Never a failure.
+export class Skip extends Schema.TaggedError<Skip, { readonly brand: 'Skip' }>()('Skip', {
+  reason: Schema.String,
+}) {}
+
+// Hands a work item to a person: the flow labels it and no flow picks it up again.
+export class NeedsHuman extends Schema.TaggedError<NeedsHuman, { readonly brand: 'NeedsHuman' }>()('NeedsHuman', {
+  reason: Schema.String,
+}) {}
+
+export class GitHubError extends Schema.TaggedError<GitHubError, { readonly brand: 'GitHubError' }>()('GitHubError', {
+  message: Schema.String,
+}) {}
+
+export class GitError extends Schema.TaggedError<GitError, { readonly brand: 'GitError' }>()('GitError', {
+  message: Schema.String,
+}) {}
+
+export class AgentError extends Schema.TaggedError<AgentError, { readonly brand: 'AgentError' }>()('AgentError', {
+  message: Schema.String,
+}) {}
+
+export class UsageError extends Schema.TaggedError<UsageError, { readonly brand: 'UsageError' }>()('UsageError', {
+  message: Schema.String,
+}) {}
+
+// A step or activity that failed for any other reason, named so the run log says which.
+export class StepFailed extends Schema.TaggedError<StepFailed, { readonly brand: 'StepFailed' }>()('StepFailed', {
+  step: Schema.String,
+  message: Schema.String,
+}) {}

package/src/flow.ts

@@ -0,0 +1,155 @@
+// Flows and the durable building blocks inside them. A flow's workflow is an
+// Effect that the daemon runs durably: every activity's result is saved, so after
+// a crash or restart the workflow replays the saved results and continues after
+// the last completed one. Side effects belong inside activities, never in the
+// workflow body, because the body runs again on every replay.
+
+import * as Context from 'effect/Context';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type * as FileSystem from 'effect/FileSystem';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import type * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import * as Schema from 'effect/Schema';
+import type * as Scope from 'effect/Scope';
+import * as Activity from 'effect/workflow/Activity';
+import * as DurableClock from 'effect/workflow/DurableClock';
+import * as DurableDeferred from 'effect/workflow/DurableDeferred';
+import type * as WorkflowEngine from 'effect/workflow/WorkflowEngine';
+
+import { NeedsHuman, Skip, StepFailed } from './errors.ts';
+import type { Json } from './json.ts';
+import { type Agent, type Git, type GitHub, type Repo, type Run, RunLog, type Usage, type WorkItem, type Worktree } from './services.ts';
+
+// Runs a step from .chernabog/stages/ in its own process. Provided by Chernabog.
+export class StepRunner extends Context.Service<
+  StepRunner,
+  {
+    run(name: string, input: Json): Effect.Effect<Json, Skip | StepFailed>;
+  }
+>()('@chernabog/sdk/StepRunner') {}
+
+// Records that a run waits on a signal, so the next tick's trigger can wake it. Provided by Chernabog.
+export class Signals extends Context.Service<
+  Signals,
+  {
+    register(signal: string, deferred: string, token: string): Effect.Effect<void>;
+  }
+>()('@chernabog/sdk/Signals') {}
+
+export type TriggerServices = Repo | GitHub | Git | Worktree | Usage | Agent | RunLog | FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner;
+
+export type WorkflowServices =
+  | TriggerServices
+  | Run
+  | StepRunner
+  | Signals
+  | WorkflowEngine.WorkflowEngine
+  | WorkflowEngine.WorkflowInstance
+  | Scope.Scope;
+
+export type FlowError = Skip | NeedsHuman | StepFailed;
+
+// What a flow's trigger, gate and workflow may fail with: anything, which the engine reports by its message.
+export type FlowFailure = { readonly _tag: string } | Error;
+
+export type Flow = {
+  // The work items in the state this flow acts on, such as issues labelled auto:eligible.
+  readonly trigger: Effect.Effect<ReadonlyArray<WorkItem>, FlowFailure, TriggerServices>;
+  // Checked before each run starts; fail with Skip to hold the run back, such as on usage.
+  readonly gate?: Effect.Effect<void, FlowFailure, TriggerServices>;
+  // Runs of this flow in one repo at once. Defaults to 1; machine limits still apply.
+  readonly concurrency?: number;
+  // A cron schedule for the trigger, overriding the repo's default.
+  readonly schedule?: string;
+  // The durable work for one item. Its result, if a string, is the run's summary.
+  readonly workflow: (item: WorkItem) => Effect.Effect<string | void, FlowFailure, WorkflowServices>;
+};
+
+export const defineFlow = (flow: Flow): Flow => flow;
+
+const FlowErrorSchema = Schema.Union([Skip, NeedsHuman, StepFailed]);
+const isFlowError = Schema.is(FlowErrorSchema);
+
+// An error's message, whatever shape it came in.
+export const describeError = <E>(error: E): string => {
+  if (Predicate.hasProperty(error, 'step') && Predicate.hasProperty(error, 'message')) return `${String(error.step)}: ${String(error.message)}`;
+
+  if (Predicate.hasProperty(error, 'message') && Predicate.isString(error.message)) return error.message;
+
+  if (Predicate.hasProperty(error, 'reason') && Predicate.isString(error.reason)) return error.reason;
+
+  return String(error);
+};
+
+// Keeps the SDK's own outcomes, and names the activity in any other failure.
+const toFlowError =
+  (name: string) =>
+  <E>(error: E): FlowError => {
+    if (isFlowError(error)) return error;
+
+    return new StepFailed({ step: name, message: describeError(error) });
+  };
+
+const withRunLog = (use: (log: RunLog['Service']) => Effect.Effect<void>) =>
+  Effect.serviceOption(RunLog).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: use })));
+
+// One durable step of a workflow. It runs once; its result is saved, and a
+// replay returns the saved result. Names must be unique within a run, so a
+// step inside a loop carries its round: `fix-ci-2`. `success` is the result's
+// schema, which the journal stores it with; leave it out for a step that
+// returns nothing.
+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) =>
+  Activity.make({
+    name,
+    success,
+    error: FlowErrorSchema,
+    execute: withRunLog((log) => log.step(name)).pipe(
+      Effect.andThen(execute),
+      Effect.ensuring(withRunLog((log) => log.stepDone(name))),
+      Effect.mapError(toFlowError(name)),
+    ),
+  });
+
+// Runs .chernabog/stages/<name>.ts (or an executable <name>) in a child
+// process, checks its output against `output`, and saves the result. `id`
+// tells apart two runs of one step in a run.
+export const step = <A>(name: string, input: Json, output: Schema.Codec<A, Json>, id: Option.Option<string> = Option.none()) =>
+  activity(
+    Option.match(id, { onNone: () => name, onSome: (suffix) => `${name}#${suffix}` }),
+    StepRunner.use((runner) => runner.run(name, input)).pipe(
+      Effect.flatMap((raw) => Schema.decodeEffect(output)(raw).pipe(Effect.mapError((issue) => new StepFailed({ step: name, message: `output: ${issue.message}` })))),
+    ),
+    output,
+  );
+
+// A durable pause: it survives restarts, and a timer that came due while the
+// daemon was down fires as soon as it is back.
+export const sleep = (name: string, duration: Duration.Input) => DurableClock.sleep({ name, duration, inMemoryThreshold: Duration.zero });
+
+// The durable deferred behind one wait, by name. Chernabog completes it with `true` when the signal comes.
+export const signalDeferred = (name: string) => DurableDeferred.make(name, { success: Schema.Literal(true) });
+
+export type Wait = { readonly id: string; readonly timeout: Duration.Input };
+
+// Waits for whichever comes first: one of the signals, which a trigger reports
+// for this run's work item (see WorkItem.signals), or the timeout. Returns the
+// signal's name, or "timeout". `id` makes each wait in a loop distinct:
+// `awaitSignal(["pushed", "closed"], { id: "round-2", timeout: "6 hours" })`.
+export const awaitSignal = (signals: ReadonlyArray<string>, wait: Wait) =>
+  Effect.gen(function* () {
+    const waits = signals.map((signal) => ({ signal, deferred: signalDeferred(`${signal}:${wait.id}`) }));
+
+    for (const pending of waits) {
+      const token = yield* DurableDeferred.token(pending.deferred);
+      yield* activity(`await-${pending.deferred.name}`, Signals.use((registry) => registry.register(pending.signal, pending.deferred.name, token)));
+    }
+
+    const [first, ...rest] = [
+      ...waits.map((pending) => DurableDeferred.await(pending.deferred).pipe(Effect.as(pending.signal))),
+      sleep(`timeout:${wait.id}`, wait.timeout).pipe(Effect.as('timeout')),
+    ];
+
+    return yield* DurableDeferred.raceAll({ name: `race:${wait.id}`, success: Schema.String, error: Schema.Never, effects: [first, ...rest] });
+  });