@sanoma-ai/workflows 0.6.0 → 0.7.1

package/src/schedules.ts

@@ -0,0 +1,206 @@
+import { DBOS, type ScheduledWorkflowFn, type WorkflowSchedule } from "@dbos-inc/dbos-sdk";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import type { ResolvedConfig } from "./config.ts";
+import { type Db, WAKEUP_TABLE } from "./db.ts";
+import type { Principal, WorkflowDefinition } from "./define.ts";
+import { readPeople, admit } from "./resources.ts";
+import type { WorkerState } from "./run.ts";
+import { errorMessage, SCHEDULE_AGENT } from "./shared.ts";
+
+// Server-only: the worker's side of `trigger: { schedule, timezone? }`. DBOS fires the schedules
+// (its scheduler, `DBOS.applySchedules`); this names them, keeps them to the config's, fires a
+// tick missed while the instance was stopped, and decides each scheduled start.
+
+/** A workflow on a schedule: its cron expression of five fields, and the IANA time zone it is read in. */
+export interface ScheduledWorkflow {
+  name: string;
+  schedule: string;
+  /** UTC when the trigger names none: DBOS would read the cron in the process's own zone. */
+  timezone: string;
+}
+
+/** The config's workflows on a schedule, in the config's order. */
+export const scheduledWorkflows = ({ workflows }: Pick<ResolvedConfig, "workflows">): ScheduledWorkflow[] =>
+  [...workflows.values()].flatMap(({ name, trigger }) =>
+    trigger === "manual" ? [] : [{ name, schedule: trigger.schedule, timezone: trigger.timezone ?? "UTC" }],
+  );
+
+/**
+ * A workflow's schedule's name in DBOS: `<appName>/<workflow>`. Names are unique across every app
+ * on the system database, so the app's name comes first, and the app's own are those under it.
+ */
+const scheduleName = (appName: string, workflow: string): string => `${appName}/${workflow}`;
+
+/**
+ * Makes DBOS's schedules of the app the config's: one per scheduled workflow (`scheduleName`),
+ * firing it by its registered function in `registry` on the app's queue, with DBOS's automatic
+ * backfill (from the schedule's last fire); every other schedule under the app's name is deleted.
+ * Each keeps, as its context, from when its ticks are due (`since`). Then, when the instance last
+ * stopped (`sanoma_wakeup.stopped_at`), it fires once each tick missed since, of a schedule that
+ * has never fired, which DBOS's backfill leaves out, never one from before `since`, and moves
+ * `since` to now. A repeat is harmless anyway: a tick's run id is its time, so DBOS starts it once.
+ * Only the app's latest version calls this (`startWorker`): an older one must not undo a newer's.
+ */
+export async function applyScheduled(
+  resolved: Pick<ResolvedConfig, "appName" | "queueName" | "workflows">,
+  registry: ReadonlyMap<string, ScheduledWorkflowFn>,
+  db: () => Promise<Db>,
+): Promise<void> {
+  const { appName, queueName } = resolved;
+  const before = new Map(
+    (await DBOS.listSchedules({ scheduleNamePrefix: scheduleName(appName, "") })).map((s) => [s.scheduleName, s]),
+  );
+  const now = new Date();
+  const declared = scheduledWorkflows(resolved).map(({ name, schedule, timezone }) => {
+    const named = scheduleName(appName, name);
+    // A schedule whose cron or zone changed is a new one: its ticks before now were never due.
+    const prior = before.get(named);
+    const same = prior?.schedule === schedule && (prior.cronTimezone ?? "UTC") === timezone;
+    const since = (same && sinceOf(prior)) || now;
+    const context: ScheduleContext = { since: since.toISOString() };
+    return {
+      since,
+      schedule: {
+        scheduleName: named,
+        workflowFn: registry.get(name)!,
+        schedule,
+        cronTimezone: timezone,
+        automaticBackfill: true,
+        queueName,
+        context,
+      },
+    };
+  });
+  if (declared.length) await DBOS.applySchedules(declared.map((d) => d.schedule));
+  const names = new Set(declared.map((d) => d.schedule.scheduleName));
+  await Promise.all([...before.keys()].filter((name) => !names.has(name)).map((name) => DBOS.deleteSchedule(name)));
+  const unfired = declared.filter((d) => before.get(d.schedule.scheduleName)?.lastFiredAt === null);
+  if (!unfired.length) return;
+  const stoppedAt = await lastStopped(await db());
+  if (!stoppedAt) return;
+  for (const { schedule, since } of unfired) {
+    const from = stoppedAt > since ? stoppedAt : since;
+    if (from >= now) continue;
+    await DBOS.backfillSchedule(schedule.scheduleName, from, now);
+    // Fired up to now: the next start backfills from here, not over the same ticks again.
+    const covered: ScheduleContext = { since: now.toISOString() };
+    await DBOS.updateSchedule(schedule.scheduleName, { context: covered });
+  }
+}
+
+/**
+ * What a schedule keeps in DBOS's `context`: from when its ticks are the runtime's to fire, ISO
+ * 8601: when it was applied with its cron and zone, or the end of its last backfill.
+ */
+interface ScheduleContext {
+  since: string;
+}
+
+/** When the schedule was first applied, from its context; undefined for none, or one without it. */
+function sinceOf(schedule: WorkflowSchedule | undefined): Date | undefined {
+  const since = (schedule?.context as Partial<ScheduleContext> | null | undefined)?.since;
+  const at = typeof since === "string" ? new Date(since) : undefined;
+  return at && !Number.isNaN(at.getTime()) ? at : undefined;
+}
+
+/** When the instance's worker last stopped, from the wakeup's row; undefined while it never has. */
+async function lastStopped(db: Db): Promise<Date | undefined> {
+  const { rows } = await db.query<{ stopped_at: Date | null }>(`SELECT stopped_at FROM ${WAKEUP_TABLE} WHERE id = 1`);
+  return rows[0]?.stopped_at ?? undefined;
+}
+
+/** Who starts a scheduled run, as `scheduledStarter` admitted them, or why they were not. */
+export interface ScheduledStarter {
+  startedBy: Principal;
+  refused?: string;
+}
+
+/**
+ * Who starts a scheduled run: the runtime's `schedule` agent as the data files declare it
+ * (`admit`), in a step, since the files may change before a replay. A refusal is the step's
+ * answer, for the run to throw once it has started, so the ledger records it; the run starts as
+ * the agent alone then. A failure of the step itself (the worker stopping) is thrown as it is.
+ */
+export async function scheduledStarter(state: Pick<WorkerState, "root">): Promise<ScheduledStarter> {
+  const admitted = await DBOS.runStep(
+    async (): Promise<{ startedBy: Principal } | { refused: string }> => {
+      try {
+        return { startedBy: admit({ id: SCHEDULE_AGENT }, readPeople(state.root)) };
+      } catch (err) {
+        return { refused: errorMessage(err) };
+      }
+    },
+    { name: "schedule:starter" },
+  );
+  return "refused" in admitted ? { startedBy: { id: SCHEDULE_AGENT }, refused: admitted.refused } : admitted;
+}
+
+/** DBOS's cron parser (`TimeMatcher`), as its scheduler and backfill use it. */
+interface TimeMatcher {
+  match(date: Date | number): boolean;
+  /** The first instant strictly after `date` that matches; one that does not at the end of its search horizon. */
+  nextWakeupTime(date: Date | number): Date;
+}
+type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
+
+let matcherClass: TimeMatcherClass | undefined;
+
+/**
+ * DBOS's `TimeMatcher`, from `dist/src/scheduler/crontab.js` beside its main module: the package's
+ * exports leave it out (dbos-sdk 5.2.11), so it is loaded by path, and a test holds it there.
+ */
+export function timeMatcher(): TimeMatcherClass {
+  if (matcherClass) return matcherClass;
+  const require = createRequire(import.meta.url);
+  const file = join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+  const loaded = (require(file) as { TimeMatcher?: unknown }).TimeMatcher;
+  if (typeof loaded !== "function") throw new Error(`DBOS's cron parser is not in ${file} any more`);
+  return (matcherClass = loaded as TimeMatcherClass);
+}
+
+/**
+ * When `schedule` (a cron expression read in `timezone`, UTC without one) fires next, strictly
+ * after `from`: as DBOS's scheduler finds it. Throws for a schedule that never fires.
+ */
+export function nextFire(schedule: string, timezone: string | undefined, from: Date): Date {
+  const matcher = new (timeMatcher())(schedule, timezone ?? "UTC");
+  // Past a horizon of a century DBOS answers an instant that does not match, as its scheduler
+  // would wait for it and look again: a few looks find any schedule that ever fires.
+  let at = from.getTime();
+  for (let look = 0; look < 4; look++) {
+    const next = matcher.nextWakeupTime(at);
+    if (matcher.match(next)) return next;
+    at = next.getTime();
+  }
+  throw new Error("it never fires");
+}
+
+/**
+ * Throws when DBOS could not run the workflow's schedule: a cron its parser refuses (a minute of
+ * 61), or one that never fires (30 February). `resolveConfig` runs it, so the worker, the app and
+ * `sanoma check` refuse the config before any schedule is applied.
+ */
+export function checkSchedule({ name, trigger }: Pick<WorkflowDefinition, "name" | "trigger">): void {
+  if (trigger === "manual") return;
+  try {
+    nextFire(trigger.schedule, trigger.timezone, new Date());
+  } catch (err) {
+    throw new Error(`Workflow "${name}": DBOS cannot run its schedule "${trigger.schedule}": ${errorMessage(err)}`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * The earliest next fire, strictly after `from`, of the config's scheduled workflows; undefined
+ * when none is on a schedule: the deadline a schedule sets for a worker that stops when quiet.
+ */
+export function nextScheduledFire(resolved: Pick<ResolvedConfig, "workflows">, from: Date): Date | undefined {
+  let earliest: Date | undefined;
+  for (const { schedule, timezone } of scheduledWorkflows(resolved)) {
+    const next = nextFire(schedule, timezone, from);
+    if (!earliest || next < earliest) earliest = next;
+  }
+  return earliest;
+}

package/src/schema.ts

@@ -8,11 +8,12 @@ import type {
   Type,
   TypeOfAttribute,
 } from "@cedar-policy/cedar-wasm/nodejs";
+import { ChangeFacts } from "./change.ts";
 import { recordSchemaOf } from "./collection.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { jsonSchemaOf } from "./define.ts";
 import { isObject } from "./resource.ts";
-import { DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
+import { CHANGE_MERGE, DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
 
 // The Cedar schema a company's policies are validated and decided against: made from the
 // resolved config and the people, in memory for the evaluator, and written as text to
@@ -36,6 +37,9 @@ export const NAMESPACE = "Sanoma";
 /** The action group every workflow start (`workflow:<name>`) is in. */
 export const START = "start";
 
+/** The entity type a change's merge acts on (`Sanoma::Change`), its attributes the change's facts. */
+export const CHANGE = "Change";
+
 const STRING = { type: "EntityOrCommon", name: "String" } as const;
 const LONG = { type: "EntityOrCommon", name: "Long" } as const;
 const BOOL = { type: "EntityOrCommon", name: "Bool" } as const;
@@ -72,7 +76,8 @@ const WRITES = new Set(["save", "delete"]);
  *   `Target in [Collection]`; `Workflow`;
  * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with
  *   `context` `{ input, before? }`: `input` from the operation's input schema, `before` the record
- *   as it was for a collection's `save` and `delete`;
+ *   as it was for a collection's `save` and `delete`; `sanoma.change.merge` on a `Change`, whose
+ *   attributes are a change's facts (`ChangeFacts`), so a rule reads `resource.touches`;
  * - `workflow:<name>` per workflow, in the group `start`, on a `Workflow`, with its `input`.
  *
  * Zod to Cedar, through the JSON Schema of the parsed value: string and enum `String`, integer `Long`, boolean `Bool`,
@@ -97,7 +102,10 @@ function buildSchema(
     const before = collection && typeOf(recordSchemaOf(collection));
     actions[op.id] = {
       memberOf: [{ id: `effect:${op.effect}` }],
-      appliesTo: applies("Target", { ...input(op.input), ...(before && { before: optional(before) }) }),
+      appliesTo: applies(op.id === CHANGE_MERGE ? CHANGE : "Target", {
+        ...input(op.input),
+        ...(before && { before: optional(before) }),
+      }),
     };
   }
   for (const name of [...resolved.workflows.keys()].toSorted()) {
@@ -112,6 +120,7 @@ function buildSchema(
     Collection: {},
     Target: { memberOfTypes: ["Collection"] },
     Workflow: {},
+    [CHANGE]: { shape: typeOf(ChangeFacts) as RecordType<string> & { type: "Record" } },
   };
   return { [NAMESPACE]: { entityTypes, actions } };
 }
@@ -221,6 +230,10 @@ const allowsNull = (schema: unknown): boolean =>
 /** Cedar's message, with its help when it has one. */
 export const messageOf = (e: DetailedError) => (e.help ? `${e.message} (${e.help})` : e.message);
 
+/** The attributes of an entity type in the schema, when it has any (`Change`'s). */
+export const shapeOf = (schema: CedarSchemaJson, type: string) =>
+  (schema[NAMESPACE]?.entityTypes[type] as { shape?: RecordType<string> & { type: "Record" } } | undefined)?.shape;
+
 /** An action's context type in the schema: a record, when the action is there. */
 export const contextTypeOf = (schema: CedarSchemaJson, action: string) =>
   schema[NAMESPACE]?.actions[action]?.appliesTo?.context as (RecordType<string> & { type: "Record" }) | undefined;

package/src/shared.ts

@@ -1,8 +1,10 @@
 import type { RunSummary } from "./client.ts";
 import type { CredentialStatus } from "./env.ts";
 import type { ApprovalState, Approver, Principal } from "./define.ts";
+import type { OpEntry, WorkflowEntry } from "./describe.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Effect } from "./op.ts";
+import type { PreviewRequest } from "./policy.ts";
 import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import type { OutlineNode } from "./outline.ts";
 
@@ -20,6 +22,7 @@ export type { DeclaredResource, ResourceProblem } from "./resources.ts";
 export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
 export type { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 export type { CredentialStatus } from "./env.ts";
+export type { ChangeEvent, ChangeFacts, ChangeReport, ChangeState } from "./change.ts";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
 // Nothing here imports DBOS, Node or zod, so a browser bundle can carry it; the runtime uses the
@@ -52,6 +55,24 @@ export const EFFECTS = ["read", "write", "publish", "send", "money", "access"] a
 /** What a workflow start's action id starts with, as a policy names it: `workflow:<name>`. */
 export const WORKFLOW_ACTION = "workflow:";
 
+/**
+ * What to ask the policy ahead of a run of `workflow` (`Policy.preview`, the principal aside): its
+ * start, then each operation it may call, with its effect, in the run (`inRun`). The run form's
+ * will-ask line asks it for the person; the Permissions grid (`permissionsGrid`) for each group.
+ */
+export function previewRequests(
+  workflow: Pick<WorkflowEntry, "name" | "ops">,
+  ops: ReadonlyMap<string, Pick<OpEntry, "effect">>,
+): Omit<PreviewRequest, "principal">[] {
+  return [
+    { action: { id: `${WORKFLOW_ACTION}${workflow.name}` } },
+    ...workflow.ops.map((id) => {
+      const effect = ops.get(id)?.effect;
+      return { action: effect === undefined ? { id } : { id, effect }, inRun: true };
+    }),
+  ];
+}
+
 /** A site's folder name under `sites/`, its URL segment: what the app mounts and `readSites` reads. */
 export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
 
@@ -184,8 +205,30 @@ function checkField(where: string, field: string, kind: unknown): void {
  */
 export const CALL_WORKFLOW = "call";
 
-/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply and call. */
-export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW, CALL_WORKFLOW]);
+/**
+ * The built-in change workflow's name: the life of a change to the company's repository, from its
+ * pull request to its merge. The only workflow that may call `sanoma.change.*`.
+ */
+export const CHANGE_WORKFLOW = "change";
+
+/** Opens a change: its draft's branch pushed and a pull request opened for it. */
+export const CHANGE_OPEN = "sanoma.change.open";
+/** Reports Sanoma's review of a change to its host (the `sanoma` commit status). */
+export const CHANGE_REVIEW = "sanoma.change.review";
+/** Merges a change; its resource is the `Sanoma::Change`, whose attributes are its facts (`ChangeFacts`). */
+export const CHANGE_MERGE = "sanoma.change.merge";
+/** Closes a change without merging it. */
+export const CHANGE_CLOSE = "sanoma.change.close";
+/** The DBOS event a change run publishes its `ChangeState` on. */
+export const CHANGE_EVENT = "change";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
+export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
+  DRIFT_WORKFLOW,
+  APPLY_WORKFLOW,
+  CALL_WORKFLOW,
+  CHANGE_WORKFLOW,
+]);
 
 /**
  * Every run status, in the order a run may pass through them: waiting on the queue, running,
@@ -277,8 +320,12 @@ export function visitorPrincipal(login: string, subject: string): Principal {
 /** Who a public page runs as when nobody is signed in. */
 export const ANONYMOUS_PRINCIPAL: Principal = Object.freeze({ id: ANONYMOUS, groups: [] });
 
-/** The runtime's own agents (scenarios, the host check, scheduled runs), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", "schedule"];
+/** The runtime's agent that registers the instance's wakeup (`register`'s `CallContext.by`). */
+export const WAKEUP_AGENT = "wakeup";
+/** The runtime's agent a scheduled run is started by (`trigger: { schedule }`): the policy decides its starts. */
+export const SCHEDULE_AGENT = "schedule";
+/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
+export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", SCHEDULE_AGENT, WAKEUP_AGENT];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>

package/src/source.ts

@@ -1,12 +1,14 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { z } from "zod";
+import type { PermissionsGrid } from "./grid.ts";
 import { defineConnector, defineDriver, DriverError } from "./op.ts";
 
 // Where a company's files live, and how a change to them is recorded: a git repository on this
 // machine, or one a host cloned. The runtime's writers (the app's Adopt, apply's lockfile) change
 // files under `root`, then commit them through it. The launcher makes one; a config without one
-// writes the files and commits nothing.
+// writes the files and commits nothing. A writer that must leave the live checkout alone writes
+// in a draft instead: a checkout of its own, on a branch of its own.
 
 /** A company's repository, as the runtime writes to it. */
 export interface Source {
@@ -21,10 +23,63 @@ export interface Source {
     message: string;
     author: string;
   }): { revision: string } | undefined | Promise<{ revision: string } | undefined>;
-  /** The revision `ref` names, the checked-out one by default. */
+  /** The revision `ref` names, the checked-out one by default (a draft's by its `branch`). */
   head(ref?: string): string | Promise<string>;
-  /** Pushes `ref` to the repository at `url`, signed in with `token`. */
+  /** Pushes `ref` to the repository at `url`, signed in with `token` (a draft by its `branch`). */
   push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
+  /**
+   * The draft `id` (letters, digits, `_` and `-`), opened: made from the checked-out revision the
+   * first time, then the same one, edits and all, until its branch is deleted.
+   */
+  draft?(id: string): Promise<Draft>;
+  /** The open drafts' ids, sorted. */
+  drafts?(): Promise<string[]>;
+  /** What the draft `id` has committed since its branch left the checked-out one (read from the branch alone). */
+  diff?(id: string): Promise<DraftDiff>;
+  /** Closes the draft `id`: its checkout removed and its branch deleted, whatever it held; nothing when it is gone. */
+  closeDraft?(id: string): Promise<void>;
+  /**
+   * `sanoma check` on the draft `id`, as a child in its checkout, one at a time in the process. A
+   * check that gives no result (a config that does not load, no install, a timeout) is a result
+   * of one problem saying why.
+   */
+  check?(id: string): Promise<CheckResult>;
+  /** The URL of the repository this one was cloned from (`origin`); undefined when it has none. */
+  remoteUrl?(): Promise<string | undefined>;
+  /**
+   * Fast-forwards the checked-out branch to `ref` in the repository at `url`, signed in with
+   * `token`, as `push` is: only when `ref` is checked out, nothing is uncommitted and the remote's
+   * `ref` contains it; otherwise `skipped`, saying why. The checked-out revision after.
+   */
+  follow?(target: { url: string; token: string; ref: string }): Promise<{ revision: string } | { skipped: string }>;
+}
+
+/**
+ * A draft: a checkout of its own, at `root`, on `branch`, which `commit` records in as
+ * `Source.commit` does in its root. Its `node_modules` may be the root's own install, linked in:
+ * a writer never writes under it.
+ */
+export interface Draft {
+  branch: string;
+  root: string;
+  commit: Source["commit"];
+}
+
+/** A draft's change: the files it touches, relative to the root, and git's `--stat` of it. */
+export interface DraftDiff {
+  files: string[];
+  summary: string;
+}
+
+/** What `sanoma check` finds in a repo (a draft's too). */
+export interface CheckResult {
+  ok: boolean;
+  /** One printable line each: `<file>:<line>:<col>: <message>`, or `<scenario> › <step>: <message>`. */
+  problems: string[];
+  /** What is worth fixing but not wrong, one line each, `<file>:<line>:<col>: warning: <message>`: the sites' `warnings`. */
+  warnings: string[];
+  /** The repo's Permissions grid (`permissionsGrid`), when its config loaded and its policies hold: what a change is reviewed by. */
+  grid?: PermissionsGrid;
 }
 
 /**
@@ -80,3 +135,121 @@ export async function resolveRevision(url: string, ref: string): Promise<string>
   }
   throw new DriverError(`${url} has no branch or tag ${ref}`, { retryable: false, vendorCode: "no_such_ref" });
 }
+
+// A git host's side of a change: the pull request a branch is reviewed in, merged through and
+// closed by, the `sanoma` commit status the review card links from, whether the host refuses a
+// change to `main` that is not a merge, and the host's webhooks. A connector carries it as its
+// remote half (`ConnectorSetup.remote`), the way a login or a model half is carried.
+
+/** A repository on a host: `owner/name`. */
+export interface RepoRef {
+  owner: string;
+  name: string;
+}
+
+/** A pull request (a merge request, on a host that calls it so), as a change follows it. */
+export interface PullRequest {
+  number: number;
+  /** Its page on the host. */
+  url: string;
+  /** The branch it merges. */
+  branch: string;
+  /** The branch's commit it was read at. */
+  head: string;
+  state: "open" | "closed" | "merged";
+  /** The commit its merge made on the base branch, once merged. */
+  mergeSha?: string;
+}
+
+/**
+ * Whether the host refuses a change to a branch that does not follow the rules: `pullRequest`
+ * when a direct push is refused (every change is a merge), `check` when a merge needs the
+ * `sanoma` status to pass. `reason` says why neither can be read or held, such as a plan that
+ * has no rules.
+ */
+export interface HostEnforcement {
+  pullRequest: boolean;
+  check: boolean;
+  reason?: string;
+}
+
+/**
+ * One repository on a host, opened by its remote half with the company's credentials, read when
+ * a call needs them; a half may keep a token for a few minutes (its README says how long), so a
+ * token stored later is used soon after. A failure is a `DriverError` (retryable as the host's
+ * status says).
+ */
+export interface SourceHost {
+  /**
+   * A token that writes to the repository: the company's app's on the host when it is installed
+   * on the owner, else a person's token (`prefer: "token"` asks for that one first). It is never
+   * logged; a push signs in with it. A `DriverError` whose `vendorCode` is `no_token` when there is
+   * neither.
+   */
+  token(prefer?: "app" | "token"): Promise<string>;
+  /** The pull request of `branch`: the open one, else the latest; undefined when it has none. */
+  pullRequestFor(branch: string): Promise<PullRequest | undefined>;
+  pullRequest(number: number): Promise<PullRequest>;
+  /** Opens a pull request of `branch` into `base`; the open one when `branch` has one already. */
+  openPullRequest(request: { branch: string; base: string; title: string; body: string }): Promise<PullRequest>;
+  /**
+   * Squash-merges pull request `number` when its branch is still at `sha`, as one commit titled
+   * `title`. A `DriverError` whose `vendorCode` is `head_moved` when the branch moved on, and
+   * `not_mergeable` when the host refuses the merge (a conflict, a rule).
+   */
+  mergePullRequest(number: number, merge: { sha: string; method: "squash"; title?: string }): Promise<{ sha: string }>;
+  closePullRequest(number: number): Promise<void>;
+  /** Deletes `branch`; nothing when it is gone already. */
+  deleteBranch?(branch: string): Promise<void>;
+  /** Sets the `sanoma` status on commit `sha`, linking to `targetUrl`. */
+  setStatus(status: {
+    sha: string;
+    state: "pending" | "success" | "failure";
+    description: string;
+    targetUrl?: string;
+  }): Promise<void>;
+  /** What the host enforces on `base` (see `HostEnforcement`). */
+  enforcement(base: string): Promise<HostEnforcement>;
+  /** Uploads a PNG the pull request's comment shows; its URL. */
+  uploadImage?(png: Uint8Array, name: string): Promise<string>;
+  /** Writes the pull request's comment that carries `marker`, once: a second call edits it. */
+  upsertComment?(number: number, marker: string, body: string): Promise<void>;
+}
+
+/** What a host's webhook says happened: a branch pushed, or a pull request closed (merged or not). */
+export type RemoteEvent =
+  | { kind: "pushed"; repo: RepoRef; branch: string; head: string }
+  | { kind: "closed"; repo: RepoRef; branch: string; number: number; merged: boolean; sha?: string };
+
+/** What a remote half reads the company's credentials with, as a login or a model half reads them. */
+export interface RemoteContext {
+  /** Secrets' values by name: the environment's first, then the stored credentials (`LoginContext.secrets`). */
+  secrets(names: readonly string[]): Promise<Map<string, string>>;
+}
+
+/** A connector's remote half (`ConnectorSetup.remote`): a git host's repositories, made once per resolved config. */
+export interface RemoteHalf {
+  /** The repository a clone URL of this host names, or undefined for another host's. */
+  matches(url: string): RepoRef | undefined;
+  /** The repository `repo`, with the company's credentials. */
+  open(repo: RepoRef, context: RemoteContext): SourceHost;
+  /**
+   * The events a webhook request carries, once its signature is verified: throws for a missing or
+   * bad signature, and answers `[]` for an event the change workflow does not follow.
+   */
+  webhook?(request: Request, context: RemoteContext): Promise<RemoteEvent[]>;
+  /** The accounts the company's app on the host is installed on: where it acts with no person's token. */
+  owners?(context: RemoteContext): Promise<{ login: string; kind: "user" | "organization" }[]>;
+}
+
+/** The remote half among `remotes` (`ResolvedConfig.remotes`) whose host `url` is on, with its vendor and the repository. */
+export function remoteFor(
+  remotes: ReadonlyMap<string, RemoteHalf>,
+  url: string,
+): { vendor: string; remote: RemoteHalf; repo: RepoRef } | undefined {
+  for (const [vendor, remote] of remotes) {
+    const repo = remote.matches(url);
+    if (repo) return { vendor, remote, repo };
+  }
+  return undefined;
+}

package/src/supervisor.ts

@@ -0,0 +1,102 @@
+import type { SanomaConfig } from "./config.ts";
+import type { SelfStop } from "./deadlines.ts";
+import { warn } from "./log.ts";
+import { errorMessage } from "./shared.ts";
+import { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
+
+// One worker at a time in a process that outlives it. A worker that stops itself when idle (a
+// wakeup declared) cannot launch again, so the next write that needs one, or the wakeup's wake,
+// starts a fresh worker. `sanoma serve` runs its worker through it, and so does the testing
+// kit's host in this process.
+
+/** A worker under a supervisor (`superviseWorker`). */
+export interface Supervisor {
+  /** True from the moment the worker stopped itself until a fresh one starts. */
+  readonly stopped: boolean;
+  /**
+   * Starts a fresh worker when the last one stopped itself, for a write that needs one (a run's
+   * start, an approval's decision); while one starts or runs, it is heard (below). Resolves once it runs, or
+   * once its failure to start is logged: the next call tries again. Never rejects.
+   */
+  resume(): Promise<void>;
+  /**
+   * A wakeup's `GET /wake`: `resume` when the worker stopped itself; a no-op while one starts or
+   * runs. A wake that arrives late, twice or for a replaced registration starts a worker that
+   * finds nothing to do and stops again on its own check.
+   */
+  wake(): Promise<void>;
+  /** Stops the worker running or starting, and starts none again. */
+  stop(): Promise<void>;
+}
+
+export interface SupervisorOptions extends Omit<WorkerOptions, "onStopped"> {
+  /**
+   * False: the worker never stops itself, as on an app on this machine alone, whose wakeup
+   * would wake the instance the host runs. Default true.
+   */
+  selfStop?: boolean;
+  /** Told each time the worker stops itself, once a fresh one is starting for a write it heard, or `stopped` is true. */
+  onStopped?: (stopped: SelfStop) => void;
+}
+
+/**
+ * Starts a worker on `config` that stops itself when idle with a wakeup declared (`onStopped`
+ * in `WorkerOptions`), and a fresh one each time `resume` or `wake` asks after it did. Throws
+ * when the first does not start. A write heard while a worker starts or runs may land after its last check
+ * for being idle, so a worker that stops itself after one is started again at once: it stops
+ * again on its own when nothing came of it.
+ */
+export async function superviseWorker(config: SanomaConfig, options: SupervisorOptions = {}): Promise<Supervisor> {
+  const { onStopped, selfStop = true, ...workerOptions } = options;
+  let worker: Worker | undefined;
+  let starting: Promise<void> | undefined;
+  let closed = false;
+  // A write while the worker starts or runs, since it began starting.
+  let heard = false;
+
+  const launch = async () => {
+    heard = false;
+    const started = await startWorker(config, { ...workerOptions, ...(selfStop && { onStopped: selfStopped }) });
+    if (closed) await started.stop();
+    else worker = started;
+  };
+  const selfStopped = (stopped: SelfStop) => {
+    worker = undefined;
+    if (closed) return;
+    // Resumed first, so `stopped` is false when `onStopped` looks.
+    if (heard) void supervisor.resume();
+    onStopped?.(stopped);
+  };
+
+  const supervisor: Supervisor = {
+    get stopped() {
+      return !closed && !worker && !starting;
+    },
+    resume() {
+      if (closed) return Promise.resolve();
+      if (worker) {
+        heard = true;
+        return Promise.resolve();
+      }
+      if (starting) {
+        heard = true;
+        return starting;
+      }
+      return (starting = launch()
+        .catch((err: unknown) => warn(`the worker could not start again: ${errorMessage(err)}`))
+        .finally(() => {
+          starting = undefined;
+        }));
+    },
+    wake: () => (supervisor.stopped ? supervisor.resume() : Promise.resolve()),
+    async stop() {
+      closed = true;
+      await starting;
+      const running = worker;
+      worker = undefined;
+      await running?.stop();
+    },
+  };
+  await launch();
+  return supervisor;
+}