@sanoma-ai/workflows 0.7.0 → 0.7.1

package/src/fake.ts

@@ -9,6 +9,9 @@ import {
   type Specs,
   withSetup,
 } from "./op.ts";
+import { fail, type Instance, UNREGISTERED, type WakeupApi, wakeupCalls } from "./wakeup-driver.ts";
+import { INSTANCE_TOKEN, instanceUrl } from "./wakeup-service.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 
 /*
  * Fake vendors for tests, at `@sanoma-ai/workflows/fake`. Kept off the main entry so the
@@ -166,3 +169,137 @@ export function defineFake<V extends string, S extends Specs, T extends Record<s
 export function withFake<C extends Connector<any, any>>(connector: C, fake: Fake<any, any>): C {
   return withSetup(connector, { driver: () => fake.driver, fake: () => fake });
 }
+
+// The built-in `sanoma.wakeup`'s fake: an in-memory wakeup service that calls the host's `/wake`.
+
+/** An instance of the fake wakeup service, as it keeps one. */
+interface FakeInstance extends Instance {
+  token: string;
+}
+
+interface FakeWakeupState extends Record<string, unknown> {
+  seq: number;
+  instances: Record<string, FakeInstance>;
+}
+
+/** How long the fake waits before it sends a wake again that the host did not answer. */
+const RETRY_MS = 250;
+/** setTimeout's longest delay: a longer one fires at once. */
+const MAX_DELAY_MS = 2 ** 31 - 1;
+
+/** The URL as the service keeps it (`instanceUrl`, its own rule), or the service's 400. */
+function checkedUrl(value: string): string {
+  const checked = instanceUrl(value);
+  if ("error" in checked) throw fail(checked.error, 400);
+  return checked.url;
+}
+
+/**
+ * An in-memory wakeup service for tests, as `sanoma wakeup` answers: instances in
+ * `state.instances`, ids made in order (UUID-shaped), each named by the token it was posted with
+ * (the call's `SANOMA_WAKEUP_TOKEN`), so posting it again moves it. `register` takes only the
+ * instance's own token and replaces the wake it had; it then sends `GET {host}/wake` at `at`,
+ * again every 250 ms until the host answers 2xx. `fire()` sends every armed wake now; `close()`
+ * (and `reset()`) disarms them.
+ */
+export function fakeSanomaWakeup(options: FakeOptions = {}) {
+  /** The wake each instance waits to send, by its id. */
+  const armed = new Map<string, { at: number; url: string; timeout?: NodeJS.Timeout; sending?: boolean }>();
+  const disarm = (id: string) => {
+    clearTimeout(armed.get(id)?.timeout);
+    armed.delete(id);
+  };
+  /** Sends `id`'s armed wake once it is due, while it is still the one armed, until the host answers. */
+  const send = async (id: string, pending = armed.get(id)) => {
+    // One request at a time: the one in flight sends again if it is not answered.
+    if (!pending || armed.get(id) !== pending || pending.sending) return;
+    const due = pending.at - Date.now();
+    if (due > 0) {
+      pending.timeout = setTimeout(() => void send(id, pending), Math.min(due, MAX_DELAY_MS)).unref();
+      return;
+    }
+    pending.sending = true;
+    const answered = await fetch(`${pending.url}/wake`).then(
+      (res) => res.ok,
+      () => false,
+    );
+    pending.sending = false;
+    if (armed.get(id) !== pending) return;
+    if (answered) armed.delete(id);
+    else pending.timeout = setTimeout(() => void send(id, pending), RETRY_MS).unref();
+  };
+
+  const api = (state: FakeWakeupState): WakeupApi => ({
+    async put(url, token) {
+      const checked = checkedUrl(url);
+      if (!INSTANCE_TOKEN.test(token)) throw fail("token must be an instance's token", 400);
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (mine) {
+        // The same instance, moved: its wake there forgotten.
+        if (mine.url !== checked) {
+          Object.assign(mine, { url: checked, ...UNREGISTERED });
+          disarm(mine.id);
+        }
+        return { id: mine.id };
+      }
+      const id = `00000000-0000-4000-8000-${String(++state.seq).padStart(12, "0")}`;
+      state.instances[id] = { id, url: checked, ...UNREGISTERED, token };
+      return { id };
+    },
+    async get(id) {
+      const found = state.instances[id];
+      if (!found) return undefined;
+      const { token: _, ...shown } = found;
+      return shown;
+    },
+    async remove(id) {
+      delete state.instances[id];
+      disarm(id);
+    },
+    async wake({ at }, token) {
+      // The token names the instance.
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (!mine) throw fail("the token is no instance's", 401);
+      Object.assign(mine, { at: new Date(at).toISOString(), lastError: null });
+      disarm(mine.id);
+      armed.set(mine.id, { at: Date.parse(at), url: mine.url });
+      void send(mine.id);
+    },
+  });
+
+  const fake = defineFake(
+    wakeupOps,
+    {
+      initial: (): FakeWakeupState => ({ seq: 0, instances: {} }),
+      ops: (state) => ({ wakeup: wakeupCalls(() => api(state)) }),
+    },
+    options,
+  );
+  const close = () => {
+    for (const id of armed.keys()) disarm(id);
+  };
+  const { reset } = fake;
+  return Object.assign(fake, {
+    /** Sends every armed wake now, whatever its `at`; resolves once the hosts answered them, or fails after 60 s. */
+    async fire() {
+      const fired = [...armed].map(([id, pending]) => {
+        clearTimeout(pending.timeout);
+        pending.at = 0;
+        void send(id, pending);
+        return pending;
+      });
+      const until = Date.now() + 60_000;
+      while (fired.some((p) => [...armed.values()].includes(p))) {
+        if (Date.now() > until) throw new Error("sanoma.wakeup fake: a fired wake was not answered in 60 s");
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    /** Disarms every armed wake. */
+    close,
+    /** Empties the state and disarms every armed wake. */
+    reset() {
+      close();
+      reset();
+    },
+  });
+}

package/src/host.ts

@@ -7,14 +7,13 @@ import type { z } from "zod";
 /**
  * How a host keeps the runtime up:
  * - `long-lived`: the process is restarted if it exits, and never stopped for being quiet (Docker).
- * - `stops-on-exit`: the host stops the instance when its process exits, and starts it again on
- *   the next request (Fly).
  * - `stops-when-quiet`: the host stops the instance after a while without inbound requests, and
  *   starts it again on the next request (a free Render service, Cloudflare Containers).
  *
  * A host that stops needs a declared `Wakeup` for what is due at a time while it is stopped.
+ * Later: `stops-on-exit`, with a host that stops the instance when its process exits (Fly).
  */
-export type HostLifetime = "long-lived" | "stops-on-exit" | "stops-when-quiet";
+export type HostLifetime = "long-lived" | "stops-when-quiet";
 
 /** What a host can do, for choosing one. */
 export interface HostCapabilities {
@@ -62,7 +61,7 @@ export interface HostSpec {
   outputs: (state: Record<string, unknown>) => HostOutputs;
 }
 
-const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-on-exit", "stops-when-quiet"];
+const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
 
 /** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
 export function hasPath(schema: z.ZodType, path: string): boolean {

package/src/index.ts

@@ -149,8 +149,6 @@ export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
 export { superviseWorker, type Supervisor, type SupervisorOptions } from "./supervisor.ts";
 export type { DeadlineSource, Deadlines, SelfStop, Wait } from "./deadlines.ts";
-// Whether a wake is the one the instance's worker last registered, for the `/wake` route.
-export { shouldWake } from "./db.ts";
 export { nextFire, nextScheduledFire } from "./schedules.ts";
 // `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
 export {
@@ -166,9 +164,17 @@ export {
   type CheckResult,
   type Draft,
   type DraftDiff,
+  type HostEnforcement,
+  type PullRequest,
+  type RemoteContext,
+  type RemoteEvent,
+  type RemoteHalf,
+  remoteFor,
+  type RepoRef,
   resolveRevision,
   SOURCE_RESOLVE,
   type Source,
+  type SourceHost,
 } from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
 export {
@@ -186,7 +192,6 @@ export {
   type WakeupOutputs,
   type WakeupRegistration,
   type WakeupSpec,
-  wakeGeneration,
   wakeupHostTypes,
 } from "./wakeup.ts";
 export {

package/src/lint.ts

@@ -29,7 +29,7 @@ const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connect
 const REFUSED_PACKAGES: [RegExp, string][] = [
   [/^@sanoma-ai\/testing(\/|$)/, `fakes and test helpers belong in tests; ${THROUGH_CTX}`],
   [/^@sanoma-ai\/app(\/|$)/, "the app starts runs and decides approvals, so a workflow could approve itself"],
-  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
+  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver|remote)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
   [/^sanoma\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
 ];
 

package/src/op.ts

@@ -2,6 +2,7 @@ import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
 import type { Secrets } from "./secret.ts";
+import type { RemoteHalf } from "./source.ts";
 import type { Steps } from "./steps.ts";
 
 /**
@@ -308,7 +309,8 @@ export interface Driver {
  * to call: the config then names the connector alone, and never a driver, a fake, steps or a
  * login. Any may be missing: a workflow using an operation of a connector with no driver is
  * refused, a connector with no fake has none for sandbox runs, one with no login half signs no
- * visitor in, and one with no model half gives the app no models.
+ * visitor in, one with no model half gives the app no models, and one with no remote half hosts
+ * no repository a change is reviewed on.
  */
 export interface ConnectorSetup {
   /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
@@ -331,6 +333,11 @@ export interface ConnectorSetup {
    * and a missing one fails that call.
    */
   model?: (context: ModelContext) => ProviderV4 | Promise<ProviderV4>;
+  /**
+   * Makes the connector's remote half, a git host's pull requests, statuses and webhooks: once per
+   * resolved config (`ResolvedConfig.remotes`). It reads its credentials when called.
+   */
+  remote?: () => RemoteHalf;
 }
 
 /** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */

package/src/person.ts

@@ -68,8 +68,11 @@ const group = defineResource({
  */
 export const sanoma = { person, agent, group };
 
+/** The runtime's own vendor, as a data file imports its constructors: `import { sanoma } from "sanoma/resources"`. */
+export const SANOMA_INFO = { title: "Sanoma", package: "sanoma" };
+
 /**
  * The runtime's own connector of the people types: every config's, so its data files may declare
  * them. Its package is `sanoma`, whose `/resources` entry exports `sanoma`.
  */
-export const peopleConnector = defineConnector("sanoma", sanoma, { title: "Sanoma", package: "sanoma" });
+export const peopleConnector = defineConnector("sanoma", sanoma, SANOMA_INFO);

package/src/resources.ts

@@ -12,7 +12,8 @@ import {
 import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
 import { filesUnder } from "./paths.ts";
-import { peopleConnector } from "./person.ts";
+import { peopleConnector, sanoma } from "./person.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 import type { Span } from "./outline.ts";
 import { type Declared, type Resource, resourceTypesOf } from "./resource.ts";
 import { Principal } from "./define.ts";
@@ -144,8 +145,9 @@ export function readPeople(root: string | undefined): DeclaredPeople {
   const stamp = filesStamp(root);
   const cached = peopleRead.get(root);
   if (cached?.stamp === stamp) return cached.read;
-  const read = readDataFiles(root, [peopleConnector], undefined, (source) => DECLARES_PEOPLE.test(source));
-  const people = read.resources;
+  // With the wakeup's type, which the same constructors declare: read, and only the people's kept.
+  const read = readDataFiles(root, [peopleConnector, wakeupOps], undefined, (source) => DECLARES_PEOPLE.test(source));
+  const people = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
   // The people are never bound, so the lockfile's problems are not theirs.
   const own = read.problems.filter((p) => p.file !== LOCKFILE);
   const ids = new Map<string, DeclaredResource>();

package/src/source.ts

@@ -135,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

@@ -1,5 +1,4 @@
-import { resolveConfig, type SanomaConfig } from "./config.ts";
-import { shouldWake } from "./db.ts";
+import type { SanomaConfig } from "./config.ts";
 import type { SelfStop } from "./deadlines.ts";
 import { warn } from "./log.ts";
 import { errorMessage } from "./shared.ts";
@@ -21,10 +20,11 @@ export interface Supervisor {
    */
   resume(): Promise<void>;
   /**
-   * A wakeup's `GET /wake?generation=N`: `resume` when the worker stopped with `generation`
-   * registered (`shouldWake`); a no-op for any other, and while one starts or runs.
+   * 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(generation: number): Promise<void>;
+  wake(): Promise<void>;
   /** Stops the worker running or starting, and starts none again. */
   stop(): Promise<void>;
 }
@@ -53,7 +53,6 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
   let closed = false;
   // A write while the worker starts or runs, since it began starting.
   let heard = false;
-  let databaseUrl: string | undefined;
 
   const launch = async () => {
     heard = false;
@@ -64,7 +63,7 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
   const selfStopped = (stopped: SelfStop) => {
     worker = undefined;
     if (closed) return;
-    // Resumed first, so `stopped` is false when `onStopped` (the exit rule) looks.
+    // Resumed first, so `stopped` is false when `onStopped` looks.
     if (heard) void supervisor.resume();
     onStopped?.(stopped);
   };
@@ -89,11 +88,7 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
           starting = undefined;
         }));
     },
-    async wake(generation) {
-      if (!supervisor.stopped) return;
-      databaseUrl ??= resolveConfig(config).databaseUrl;
-      if (await shouldWake(databaseUrl, generation)) await supervisor.resume();
-    },
+    wake: () => (supervisor.stopped ? supervisor.resume() : Promise.resolve()),
     async stop() {
       closed = true;
       await starting;