@sanoma-ai/workflows 0.6.0 → 0.7.0

package/dist/source.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { PermissionsGrid } from "./grid.ts";
 /** A company's repository, as the runtime writes to it. */
 export interface Source {
     /** The repository's root directory. */
@@ -16,14 +17,72 @@ export interface Source {
     } | 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;
 }
 /**
  * The built-in operation `sanoma.source.resolve`: the commit `ref` names in the repository at

package/dist/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}

package/dist/supervisor.d.ts

@@ -0,0 +1,38 @@
+import { type SanomaConfig } from "./config.ts";
+import type { SelfStop } from "./deadlines.ts";
+import { type WorkerOptions } from "./worker.ts";
+/** 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 declare function superviseWorker(config: SanomaConfig, options?: SupervisorOptions): Promise<Supervisor>;

package/dist/supervisor.js

@@ -0,0 +1,77 @@
+import { resolveConfig } from "./config.js";
+import { shouldWake } from "./db.js";
+import { warn } from "./log.js";
+import { errorMessage } from "./shared.js";
+import { startWorker } from "./worker.js";
+/**
+ * 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, options = {}) {
+    const { onStopped, selfStop = true, ...workerOptions } = options;
+    let worker;
+    let starting;
+    let closed = false;
+    // A write while the worker starts or runs, since it began starting.
+    let heard = false;
+    let databaseUrl;
+    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) => {
+        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 = {
+        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) => 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;
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -7,8 +7,10 @@ export declare const RUNTIME_VERSION: string;
  * 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 declare const STEP_LAYOUT = 3;
+export declare const STEP_LAYOUT = 5;
 /**
  * The application version DBOS stamps on every run, always `<appName>@…`: DBOS version names
  * are unique per system database across apps. A worker recovers and dequeues only runs of its

package/dist/version.js

@@ -12,8 +12,10 @@ export const RUNTIME_VERSION = JSON.parse(readFileSync(new URL("../package.json"
  * 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;
 /** The installed DBOS SDK's version, read from its package.json (which its exports don't expose). */
 function installedDbosVersion() {

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,OAAO,EAA2B,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,eAAe,GAC1B,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC7E,CAAC,OAAO,CAAC;AAEV;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B,IAAI,WAA+B,CAAC;AAEpC,qGAAqG;AACrG,SAAS,oBAAoB;IAC3B,WAAW,KAAK,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE;QACpG,IAAI,GAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAe,CAAC;QAClF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YACvE,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,KAAK,oBAAoB,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACpF,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxF,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,OAAO,EACP,SAAS,EAAE,WAAW,GAKvB;IACC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACnD,IAAI,KAAK;QAAE,OAAO,GAAG,OAAO,IAAI,KAAK,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,WAAW;SAC1B,GAAG,CACF,CAAC,EAAE,EAAE,EAAE,CACL;QACE,EAAE,CAAC,IAAI;QACP,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE;QACjB,OAAO,CAAC,EAAE,CAAC;QACX,iGAAiG;QACjG,aAAa,CAAC,EAAE,CAAC;KACT,CACb;SACA,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC9B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,EAAE,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;SACrG,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,+GAA+G;AAC/G,SAAS,aAAa,CAAC,EAAgC;IACrD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/wakeup-service.d.ts

@@ -0,0 +1,83 @@
+/** Where the accounts live: one per party that registers instances, its token's hash alone. */
+export declare const WAKEUP_ACCOUNTS_TABLE = "sanoma_wakeup_accounts";
+/** Where the instances live: each one's URL, its token's hash and its registered wake. */
+export declare const WAKEUP_INSTANCES_TABLE = "sanoma_wakeup_instances";
+/** The shape of `@sanoma-ai/app`'s `IngressRoute`, which `startApp`'s `ingress` takes. */
+export interface WakeupRoute {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    /** `/wakeup`, with every path under it (`prefix`). */
+    path: string;
+    prefix: true;
+    handle(request: Request): Promise<Response>;
+}
+export interface WakeupServiceOptions {
+    /** The service's own Postgres: its tables are made there when missing (the database too). */
+    databaseUrl: string;
+    /** The clock: what is due, and what `called_at` and `next_attempt_at` are set from. */
+    now?: () => Date;
+    /** How the instances are called. */
+    fetch?: typeof globalThis.fetch;
+    /** One `info` line per call, a `warn` per failure; the runtime's logger by default. */
+    log?: {
+        info(line: string): void;
+        warn(line: string): void;
+    };
+}
+export interface WakeupService {
+    /** One route answering everything under `/wakeup`, for `startApp`'s `ingress` or a server of its own. */
+    routes: WakeupRoute[];
+    /** An account that may register instances: its id, and its token, shown this once. */
+    mintAccount(label: string): Promise<{
+        id: string;
+        token: string;
+    }>;
+    /** Refuses the account's token and its instances' from now on, and wakes its instances no more. */
+    revokeAccount(id: string): Promise<void>;
+    /** Ends the loop, abandoning the calls in flight (called again once their claim lapses), and closes the pool. */
+    stop(): Promise<void>;
+}
+/**
+ * A new instance token (`swi_…`), which the company mints and stores as `SANOMA_WAKEUP_TOKEN`
+ * before anything is applied, so its host is given it from the first apply; the wakeup's create
+ * then registers it with the service. The service never mints one.
+ */
+export declare const mintInstanceToken: () => string;
+/** The secret a company keeps its instance token in: what its host's `secrets` name and its wakeup's driver reads. */
+export declare const WAKEUP_TOKEN = "SANOMA_WAKEUP_TOKEN";
+/** An instance token the service takes: `swi_`, then at least as many base64url characters as a minted one has. */
+export declare const INSTANCE_TOKEN: RegExp;
+/**
+ * An instance's URL as it is stored, without a trailing slash, or why it is refused: `http(s)`, no
+ * user or password, no query, no fragment (`/wake?generation=N` is added to it).
+ */
+export declare function instanceUrl(value: unknown): {
+    url: string;
+} | {
+    error: string;
+};
+/**
+ * An account of the wakeup service on `databaseUrl`, minted without starting the service (its
+ * tables made when missing): what `sanoma wakeup account <label>` prints.
+ */
+export declare function mintWakeupAccount(databaseUrl: string, label: string): Promise<{
+    id: string;
+    token: string;
+}>;
+/**
+ * Starts the wakeup service on its own database: its two tables made when missing, its one loop
+ * running, and `routes` for whoever serves it (`sanoma wakeup`, or `sanoma serve` with
+ * `wakeup: true`). Routes, each JSON and `no-store`:
+ *
+ * - `POST /wakeup/instances { url, token }`, an account's token → 201 `{ id }` for a new instance
+ *   token, 200 `{ id }` for one the account registered already, its URL now the given one (a lost
+ *   reply, or a host that moved; its registered wake kept only when the URL is the same), 409 for
+ *   another account's
+ * - `GET /wakeup/instances/{id}`, its account's token → `{ id, url, at, generation, calledAt, attempts, lastError }`
+ * - `DELETE /wakeup/instances/{id}`, its account's token → 204
+ * - `PUT /wakeup/wake { at, generation }`, an instance's own token, which names the instance → 204,
+ *   applied only when `generation` is newer than the one it has, and waking the loop
+ *
+ * 401 without a token or with an unknown one, 403 for another account's instance, 400 for a bad
+ * body, 404 for an unknown id or path.
+ */
+export declare function startWakeupService({ databaseUrl, now, fetch, log, }: WakeupServiceOptions): Promise<WakeupService>;