@sanoma-ai/workflows 0.6.0 → 0.7.0

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;
 }
 
 /**

package/src/supervisor.ts

@@ -0,0 +1,107 @@
+import { resolveConfig, type SanomaConfig } from "./config.ts";
+import { shouldWake } from "./db.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?generation=N`: `resume` when the worker stopped with `generation`
+   * registered (`shouldWake`); a no-op for any other, and while one starts or runs.
+   */
+  wake(generation: number): 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;
+  let databaseUrl: string | undefined;
+
+  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` (the exit rule) 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;
+        }));
+    },
+    async wake(generation) {
+      if (!supervisor.stopped) return;
+      databaseUrl ??= resolveConfig(config).databaseUrl;
+      if (await shouldWake(databaseUrl, generation)) await supervisor.resume();
+    },
+    async stop() {
+      closed = true;
+      await starting;
+      const running = worker;
+      worker = undefined;
+      await running?.stop();
+    },
+  };
+  await launch();
+  return supervisor;
+}

package/src/version.ts

@@ -16,8 +16,10 @@ export const RUNTIME_VERSION = (
  * package release, so a run in flight on the old layout is not replayed against the new one.
  * 2: calls run in program order; a decision event per approval (2026-10-07).
  * 3: a start the policy holds waits on its approval before the body (2026-10-21).
+ * 4: a sleep for a duration reads DBOS's clock for its start (2026-10-25).
+ * 5: a scheduled run admits its starter and asks the policy in two steps before the body (2026-10-25).
  */
-export const STEP_LAYOUT = 3;
+export const STEP_LAYOUT = 5;
 
 let dbosVersion: string | undefined;