@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/apply-steps.d.ts

@@ -0,0 +1,6 @@
+import type { ApplyDeclared, ApplySteps } from "./apply.ts";
+/**
+ * The apply workflow's steps for a config: `read`, the data files and the lockfile as drift reads
+ * them, under `root`; `appName` scopes the search for the lockfile apply last wrote.
+ */
+export declare function applySteps(appName: string, root: string | undefined, read: () => Promise<Omit<ApplyDeclared, "rebinds">>): ApplySteps;

package/dist/apply-steps.js

@@ -0,0 +1,93 @@
+import { join, relative, sep } from "node:path";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { decide } from "./call.js";
+import { diffLockfiles, LOCKFILE, readLockfile, writeLockfile } from "./lockfile.js";
+import { currentRun } from "./run.js";
+import { APPLY_WORKFLOW } from "./shared.js";
+// The apply workflow's steps that call no vendor: reading the data files, asking the policy
+// ahead, and writing the lockfile. Here, not in apply.ts, which is held to the workflow lint and
+// imports no DBOS; each reads its run from `currentRun`.
+/** The name of the step that writes the lockfile and commits it: its output has the bindings it wrote. */
+const WRITE_STEP = "apply:lockfile";
+/** How many of the latest apply runs are searched for the lockfile one last wrote. */
+const RUNS_SEARCHED = 100;
+const runNow = () => {
+    const run = currentRun.getStore();
+    if (!run)
+        throw new Error("An apply step ran outside its run");
+    return run;
+};
+/**
+ * The bindings the latest apply run that wrote the lockfile wrote last, from its steps; undefined
+ * when none of the latest `RUNS_SEARCHED` did. A sandbox run writes none.
+ */
+async function lastWritten(appName) {
+    const runs = await DBOS.listWorkflows({
+        workflowName: APPLY_WORKFLOW,
+        applicationName: appName,
+        sortDesc: true,
+        limit: RUNS_SEARCHED,
+        loadInput: false,
+        loadOutput: false,
+    });
+    for (const { workflowID } of runs) {
+        const steps = await DBOS.listWorkflowSteps(workflowID);
+        const last = steps?.findLast((step) => step.name === WRITE_STEP && !step.error);
+        if (last)
+            return last.output.bindings;
+    }
+    return undefined;
+}
+/**
+ * The apply workflow's steps for a config: `read`, the data files and the lockfile as drift reads
+ * them, under `root`; `appName` scopes the search for the lockfile apply last wrote.
+ */
+export function applySteps(appName, root, read) {
+    return {
+        // The data files, and the lockfile against the one apply last wrote: a change someone else made.
+        declared: () => DBOS.runStep(async () => {
+            const declared = await read();
+            const before = await lastWritten(appName);
+            return { ...declared, rebinds: before ? diffLockfiles(before, declared.bindings) : [] };
+        }, { name: "apply:data-files" }),
+        // The policy asked as each call would ask it, now, so one approval can cover them all.
+        holds: (calls) => DBOS.runStep(async () => {
+            const run = runNow();
+            for (const { op: id, input } of calls) {
+                const op = run.state.ops.get(id);
+                // Parsed as the call will be, so the policy sees the same input with its defaults.
+                const parsed = op.input.safeParse(input);
+                const decision = await decide(run, op, parsed.success ? parsed.data : input);
+                if (decision.kind === "approve")
+                    return decision.approver;
+            }
+            return undefined;
+        }, { name: "apply:policy" }),
+        // The one binding changed on the lockfile as it is now, written whole, then committed, in one
+        // step whose output is what it wrote. A sandbox run keeps its lockfile in memory: the run's
+        // report has it.
+        write: async (key, binding, message) => {
+            const run = runNow();
+            if (run.sandbox !== undefined || root === undefined)
+                return { written: false };
+            const { source } = run.state;
+            const { revision } = await DBOS.runStep(async () => {
+                const now = readLockfile(root);
+                if (now.problems.length)
+                    throw new Error(`${LOCKFILE} cannot be updated: ${now.problems[0].message}`);
+                const { [key]: _, ...others } = now.bindings;
+                const bindings = binding ? { ...others, [key]: binding } : others;
+                writeLockfile(root, bindings);
+                const paths = [
+                    relative(source?.root ?? root, join(root, LOCKFILE))
+                        .split(sep)
+                        .join("/"),
+                ];
+                const committed = await source?.commit({ paths, message, author: run.actor.id });
+                return { bindings, ...(committed && { revision: committed.revision }) };
+            }, { name: WRITE_STEP });
+            return { written: true, ...(revision !== undefined && { revision }) };
+        },
+    };
+}
+//# sourceMappingURL=apply-steps.js.map

package/dist/apply-steps.js.map

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

package/dist/apply.d.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { type Approver, type WorkflowDefinition } from "./define.ts";
+import { type DriftDeclared, type DriftField, type ResolveOp } from "./drift.ts";
+import type { HostOutputs } from "./host.ts";
+import type { Binding, Bindings, Rebind } from "./lockfile.ts";
+import type { Op } from "./op.ts";
+import { type PlanAction, type Resource } from "./resource.ts";
+import type { ResourceProblem } from "./resources.ts";
+export { APPLY_WORKFLOW } from "./shared.ts";
+/** What a person answers for a bound object the vendor no longer has (`gone`), or a binding no declaration has (`orphan`). */
+export declare const PLAN_ANSWERS: readonly ["recreate", "forget", "delete"];
+export type PlanAnswer = (typeof PLAN_ANSWERS)[number];
+/**
+ * The apply workflow's input: `only` the declared ids (`<file>#<export>`) or orphaned lockfile
+ * keys to plan, else all; `bind`, a declared id to the vendor's id of the object to bind it to;
+ * `answers`, by declared id or orphaned key: `recreate` or `forget` a gone object, `forget` or
+ * `delete` an orphaned binding's.
+ */
+export declare const ApplyInput: z.ZodObject<{
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    bind: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        delete: "delete";
+        forget: "forget";
+        recreate: "recreate";
+    }>>>;
+}, z.core.$strict>;
+export type ApplyInput = z.infer<typeof ApplyInput>;
+/**
+ * One declared resource, or orphaned binding, by what apply does with it: `create` it (as the
+ * vendor plans: `planned`, the paths `unknown` until it exists), `update` or `replace` its bound
+ * object (the declared `fields` that differ, the paths that force the replace), `bind` it to an
+ * object its identity `found` or the input `given`, ask about a `gone` object or an `orphan`ed
+ * binding (unless `answer`ed), or `none`.
+ */
+export type PlanStep = {
+    id: string;
+    vendor: string;
+    type: string;
+} & ({
+    action: "create";
+    planned: Record<string, unknown>;
+    unknown: string[];
+} | {
+    action: "update" | "replace";
+    binding: string;
+    fields: DriftField[];
+    replace: string[];
+} | {
+    action: "bind";
+    binding: string;
+    source: "found" | "given";
+} | {
+    action: "gone";
+    binding: string;
+    answer?: PlanAnswer;
+} | {
+    action: "orphan";
+    key: string;
+    binding: string;
+    answer?: PlanAnswer;
+} | {
+    action: "none";
+    binding: string;
+});
+/** What apply would change: the problems, the lockfile's changes it did not make, and each step in dependency order. */
+export interface ApplyPlan {
+    problems: ResourceProblem[];
+    /** The committed lockfile against the one apply last wrote: changes someone else made. */
+    rebinds: Rebind[];
+    steps: PlanStep[];
+}
+/** What became of one step: `done` (a `none` too), `skipped` (a question unanswered), or `failed`, with why. */
+export interface ApplyResult {
+    id: string;
+    action: PlanStep["action"];
+    status: "done" | "skipped" | "failed";
+    /** Its binding after the step, when it has one. */
+    binding?: string;
+    /** For a host it created or updated: where it answers, as its state says. */
+    host?: HostOutputs;
+    error?: string;
+}
+/** The apply workflow's output. */
+export interface ApplyReport {
+    plan: ApplyPlan;
+    results: ApplyResult[];
+    /**
+     * Whether the run wrote the lockfile (a sandbox run keeps its copy in memory), the revision of
+     * its last commit, and the bindings it ended with.
+     */
+    lockfile: {
+        written: boolean;
+        revision?: string;
+        bindings: Bindings;
+    };
+}
+/** What an apply run reads first: the data files and the lockfile, as drift does, and the lockfile's rebinds. */
+export interface ApplyDeclared extends DriftDeclared {
+    bindings: Bindings;
+    orphans: (Binding & {
+        key: string;
+    })[];
+    rebinds: Rebind[];
+}
+/** One change call apply plans to make, as the policy would see it. */
+export interface PlannedCall {
+    op: string;
+    input: unknown;
+}
+/** What apply does that is no vendor call, each a step of its own (`apply-steps.ts`). */
+export interface ApplySteps {
+    declared(): Promise<ApplyDeclared>;
+    /** Who the policy would hold any of these calls for, the first it holds; undefined when it holds none. */
+    holds(calls: PlannedCall[]): Promise<Approver | undefined>;
+    /**
+     * Binds `key` to `binding` (unbinds it when undefined) in the lockfile as it is now, so a change
+     * another run made since this one read it stays, and commits it with `message`; a sandbox run
+     * writes nothing.
+     */
+    write(key: string, binding: Binding | undefined, message: string): Promise<{
+        written: boolean;
+        revision?: string;
+    }>;
+}
+type State = Record<string, unknown>;
+type Expect = {
+    action: PlanAction;
+    replace: string[];
+};
+type ImportOp = Op<string, string, "import", {
+    id: string;
+}, {
+    id: string;
+    gone: boolean;
+    state?: State;
+}>;
+type PlanOp = Op<string, string, "plan", {
+    id?: string;
+    desired?: State;
+}, {
+    action: PlanAction;
+    planned?: State;
+    unknown: string[];
+    replace: string[];
+}>;
+type CreateOp = Op<string, string, "create", {
+    desired: State;
+}, {
+    id: string;
+    state: State;
+}>;
+type UpdateOp = Op<string, string, "update", {
+    id: string;
+    desired: State;
+    expect?: Expect;
+}, {
+    id: string;
+    state: State;
+}>;
+type DeleteOp = Op<string, string, "delete", {
+    id: string;
+}, {
+    id: string;
+    gone: true;
+}>;
+type ApplyUse = ImportOp | PlanOp | CreateOp | UpdateOp | DeleteOp | ResolveOp | "approval" | "sleep";
+/**
+ * The apply workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare that has a driver, and the change operations (`plan`, `create`, `update`, `delete`) of
+ * each writable one, and `approval`. `resolveConfig` adds it beside drift, with `steps`, the
+ * steps that read the data files, ask the policy and write the lockfile.
+ *
+ * A run reads the data files, the lockfile and its rebinds (`steps.declared`), and observes each
+ * declared resource as drift does: one import each, by the binding the input gives, else the
+ * lockfile's, else its identity. Then, for each resource the input wants (`only`), each after the
+ * ones it names, it plans:
+ *
+ * - `bind` when the input gives an object (`bind`) or, unbound, its identity finds one;
+ * - `create` when unbound and nothing is found, as its type's `plan` says (a gone object of a
+ *   `stateless` type too, unless answered);
+ * - `gone` when its bound object is no longer there: skipped unless `answers` says `recreate`
+ *   (created again) or `forget` (unbound);
+ * - `update`, `replace` or `none`, as its type's `plan` says for its bound object;
+ * - `orphan` for a binding no declaration has: skipped unless `answers` says `forget` (unbound) or
+ *   `delete` (deleted at the vendor, then unbound).
+ *
+ * What cannot be planned is a problem, and has no step. When the policy would hold any of the
+ * change calls the plan makes (`steps.holds`), one approval asks for them all, covering each
+ * change operation, with the plan as its details. Then each step runs in order: a change call,
+ * and right after one that changes a binding, the lockfile written and committed
+ * (`steps.write`), so an object made is never left unbound. An update is given the plan's action
+ * and replace (`expect`), and refuses (`plan_changed`) when the vendor now plans otherwise; a
+ * reference to a resource made in this run is given its new binding. A failed step is reported
+ * and the run goes on; a failure that ends the run (`isRunControlError`) ends it.
+ */
+export declare function applyWorkflow(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>, drivers: ReadonlyMap<string, unknown>, steps: ApplySteps): WorkflowDefinition<readonly ApplyUse[], typeof ApplyInput>;