@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/writer.js

@@ -0,0 +1,201 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "./ast.js";
+import { isReference, keyName, readDataFile, SECRET_ENTRIES, } from "./datafile.js";
+import { isSecret } from "./secret.js";
+/**
+ * oxfmt's options from `<root>/.oxfmtrc.json`, what `oxfmt` itself reads there, less what only
+ * its CLI uses (`ignorePatterns`, `overrides`); none, oxfmt's defaults, without the file.
+ */
+export function formatOptions(root) {
+    let text;
+    try {
+        text = readFileSync(join(root, ".oxfmtrc.json"), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw err;
+    }
+    const { $schema: _, ignorePatterns: __, overrides: ___, ...options } = JSON.parse(text);
+    return options;
+}
+/**
+ * `source`, a data file's text, with fields of its resource `exportName` set to new values:
+ * `fields` by dotted path, a list item's with its index, as a drift report names them
+ * (`required_pull_request_reviews.0.dismiss_stale_reviews`). A field the declaration does not
+ * have is added at the end of the object that should hold it. Only that `export const` changes:
+ * it is formatted with oxfmt under `options` (`formatOptions`), and every other byte of the file
+ * stays as it was.
+ *
+ * A value naming a secret adds `import { secret } from "sanoma/resources"` after the file's
+ * imports when it has none.
+ *
+ * Throws when the file does not parse, declares no such resource, or a path cannot be set: it
+ * runs through a value that is not an object or a list, or ends at a reference to another
+ * resource (a person changes a reference; a vendor's value never replaces one).
+ */
+export async function setFields(source, exportName, fields, options = {}) {
+    let text = source;
+    // One field at a time, each against the file as the last left it: no offset goes stale.
+    for (const [path, value] of Object.entries(fields)) {
+        const { start, end, replacement } = editAt(declarationOf(text, exportName).object, path, value);
+        text = text.slice(0, start) + replacement + text.slice(end);
+    }
+    if (Object.values(fields).some(holdsSecret))
+        text = withSecretImport(text);
+    // The declaration on its own: a top-level statement formats the same in its file as alone.
+    const { start, end } = declarationOf(text, exportName).statement;
+    const formatted = await format(text.slice(start, end), options);
+    return text.slice(0, start) + formatted.trimEnd() + text.slice(end);
+}
+/** What a data file imports `secret` from when it names one (`readDataFile` lists no such import). */
+const SECRET_IMPORT = { source: "sanoma/resources", imported: "secret", local: "secret" };
+/**
+ * A whole data file: the imports, one per source, then each resource as `export const`, then
+ * `export default` naming them all, formatted with oxfmt under `options`. `readDataFile` reads it
+ * back as it was given: what `readDataFile` returns renders the file again. A file whose values
+ * name a secret also imports `secret` from "sanoma/resources".
+ */
+export async function renderDataFile({ imports, exports }, options = {}) {
+    const names = new Map();
+    const hasSecret = imports.some((i) => i.local === SECRET_IMPORT.local);
+    const all = !hasSecret && exports.some((e) => holdsSecret(e.desired)) ? [...imports, SECRET_IMPORT] : imports;
+    for (const { source, imported, local } of all) {
+        const list = names.get(source) ?? [];
+        list.push(imported === local ? local : `${imported} as ${local}`);
+        names.set(source, list);
+    }
+    const parts = [
+        [...names].map(([source, list]) => `import { ${list.join(", ")} } from ${JSON.stringify(source)};`).join("\n"),
+        // The top-level object on lines of its own, so oxfmt keeps it expanded as people write it.
+        ...exports.map(({ name, vendor, type, desired }) => {
+            const body = Object.entries(desired).map(([key, value]) => `${keyOf(key)}: ${literal(value)},\n`);
+            return `export const ${name} = ${vendor}.${type}({${body.length ? `\n${body.join("")}` : ""}});`;
+        }),
+        `export default [${exports.map((e) => e.name).join(", ")}];`,
+    ];
+    return format(`${parts.filter(Boolean).join("\n\n")}\n`, options);
+}
+/** `text` with `secret` imported after its imports, unless it imports it already. */
+function withSecretImport(text) {
+    const imports = parse("/data-file.ts", text).program.body.filter((s) => s.type === "ImportDeclaration");
+    const has = imports.some((s) => SECRET_ENTRIES.has(s.source.value) &&
+        s.specifiers.some((sp) => (sp.imported?.name ?? sp.imported?.value) === "secret"));
+    if (has)
+        return text;
+    const at = imports.at(-1)?.end ?? 0;
+    const line = `import { ${SECRET_IMPORT.local} } from ${JSON.stringify(SECRET_IMPORT.source)};`;
+    return at ? `${text.slice(0, at)}\n${line}${text.slice(at)}` : `${line}\n${text}`;
+}
+/** The `export const` of the resource `name` in `text`, and the object literal its constructor takes. */
+function declarationOf(text, name) {
+    // The name is never resolved, and a relative import is checked against the file's own directory.
+    const filename = "/data-file.ts";
+    const { program, errors } = parse(filename, text);
+    if (errors.length)
+        throw new Error(`The data file does not parse: ${errors[0].message}`);
+    const found = readDataFile(program, filename).exports.find((e) => e.name === name);
+    if (!found)
+        throw new Error(`The data file declares no resource ${name}`);
+    const statement = program.body.find((s) => s.start === found.start);
+    return { statement, object: statement.declaration.declarations[0].init.arguments[0] };
+}
+/**
+ * What setting `path` to `value` in `object` replaces, and with what. A key may hold a dot
+ * (`metadata: { "app.owner": … }`), and a drift report's path does not say so: at each object,
+ * the longest run of the path's segments that names a field is that field.
+ */
+function editAt(object, path, value) {
+    const keys = path.split(".");
+    let node = object;
+    for (let i = 0; i < keys.length;) {
+        if (node.type === "ObjectExpression") {
+            const names = new Map(node.properties.map((p) => [fieldName(p), p]));
+            let j = keys.length;
+            while (j > i && !names.has(keys.slice(i, j).join(".")))
+                j--;
+            if (j === i)
+                return added(node, keys.slice(i), path, value);
+            node = names.get(keys.slice(i, j).join(".")).value;
+            i = j;
+        }
+        else if (node.type === "ArrayExpression" && /^\d+$/.test(keys[i]) && node.elements[Number(keys[i])]) {
+            node = node.elements[Number(keys[i])];
+            i++;
+        }
+        else {
+            const at = keys.slice(0, i).join(".");
+            throw new Error(`Cannot set ${path}: ${at} is not an object or a list with item ${keys[i]}`);
+        }
+    }
+    const named = referenceIn(node);
+    if (named) {
+        throw new Error(`Cannot set ${path}: it names the resource ${named}; change a reference in the file itself`);
+    }
+    return { start: node.start, end: node.end, replacement: literal(value) };
+}
+/** The first resource a value names, itself or anywhere inside it: a vendor's value never replaces one. */
+function referenceIn(node) {
+    if (node.type === "Identifier")
+        return node.name;
+    const items = node.type === "ArrayExpression" ? node.elements : node.type === "ObjectExpression" ? node.properties : [];
+    for (const item of items) {
+        const named = item && referenceIn(item.type === "Property" ? item.value : item);
+        if (named)
+            return named;
+    }
+    return undefined;
+}
+/**
+ * The edit that adds `keys` (the first missing, then any under it) with `value` at the end of
+ * `object`. Only objects are made under it: a list item's index there is refused.
+ */
+function added(object, [key, ...under], path, value) {
+    const index = under.find((k) => /^\d+$/.test(k));
+    if (index !== undefined)
+        throw new Error(`Cannot set ${path}: the file has no list to hold item ${index}`);
+    const nested = under.reduceRight((v, k) => Object.fromEntries([[k, v]]), value);
+    const field = `${keyOf(key)}: ${literal(nested)}`;
+    const last = object.properties.at(-1);
+    return last
+        ? { start: last.end, end: last.end, replacement: `, ${field}` }
+        : { start: object.start, end: object.end, replacement: `{ ${field} }` };
+}
+/** A property's name, as `readDataFile` reads it. */
+const fieldName = (p) => (p.type === "Property" && !p.computed ? keyName(p.key) : undefined);
+/** A field's name in source: bare when it can be, else a string. */
+const keyOf = (key) => (/^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key));
+/** True when a value names a secret, itself or anywhere inside it. */
+const holdsSecret = (value) => isSecret(value) ||
+    (typeof value === "object" && value !== null && !isReference(value) && Object.values(value).some(holdsSecret));
+/** A value in the data-file subset, as source, on one line: oxfmt lays it out. */
+function literal(value) {
+    if (isReference(value))
+        return value.name;
+    if (isSecret(value))
+        return `secret(${JSON.stringify(value.$secret)}${value.generate ? ", { generate: true }" : ""})`;
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${value} cannot be written in a data file: write a finite number`);
+        return Object.is(value, -0) ? "0" : String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(literal).join(", ")}]`;
+    if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        const fields = Object.entries(value).map(([key, v]) => `${keyOf(key)}: ${literal(v)}`);
+        return fields.length ? `{ ${fields.join(", ")} }` : "{}";
+    }
+    throw new Error(`${String(value)} cannot be written in a data file: ${typeof value} is not a data value`);
+}
+/** `text` formatted by oxfmt, loaded only when a file is written. */
+async function format(text, options) {
+    const oxfmt = await import("oxfmt");
+    const { code, errors } = await oxfmt.format("data-file.ts", text, options);
+    if (errors.length)
+        throw new Error(`oxfmt could not format the data file: ${errors[0].message}`);
+    return code;
+}
+//# sourceMappingURL=writer.js.map

package/dist/writer.js.map

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

package/oxlint.json

@@ -0,0 +1,128 @@
+{
+  "overrides": [
+    {
+      "files": ["workflows/**", "policies/**"],
+      "rules": {
+        "no-restricted-globals": [
+          "error",
+          {
+            "name": "Date",
+            "message": "Workflows are replayed: use `await ctx.now()` for the time and `ctx.sleep({ until })` to wait for a date."
+          },
+          {
+            "name": "fetch",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          {
+            "name": "WebSocket",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          {
+            "name": "XMLHttpRequest",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          { "name": "setTimeout", "message": "Workflows are replayed: use `ctx.sleep`." },
+          { "name": "setInterval", "message": "Workflows are replayed: use `ctx.sleep` in a loop." },
+          { "name": "setImmediate", "message": "Workflows are replayed: use `ctx.sleep`." },
+          { "name": "queueMicrotask", "message": "Workflows are replayed: await the work directly." },
+          { "name": "performance", "message": "Workflows are replayed: use `await ctx.now()`." },
+          {
+            "name": "process",
+            "message": "Workflows are replayed: pass configuration as workflow input; drivers read the environment."
+          },
+          { "name": "crypto", "message": "Workflows are replayed: derive ids from `ctx.runId`." },
+          {
+            "name": "require",
+            "message": "Import from `@sanoma-ai/workflows`, a `@sanoma-ai/connector-*` package, zod or a file in this directory."
+          },
+          { "name": "eval", "message": "Not allowed in a workflow or policy." },
+          { "name": "Function", "message": "Not allowed in a workflow or policy." },
+          {
+            "name": "globalThis",
+            "message": "Reaching globals through globalThis would bypass these rules: use `ctx`."
+          },
+          { "name": "global", "message": "Reaching globals through global would bypass these rules: use `ctx`." }
+        ],
+        "no-restricted-properties": [
+          "error",
+          {
+            "object": "Math",
+            "property": "random",
+            "message": "Workflows are replayed: derive values from `ctx.runId` or the input."
+          },
+          {
+            "object": "Promise",
+            "property": "all",
+            "message": "Calls through ctx run one at a time; declare a fan-out with `ctx.all([...])` so the ledger and the graph show it."
+          },
+          {
+            "object": "Promise",
+            "property": "allSettled",
+            "message": "Calls through ctx run one at a time; declare a fan-out with `ctx.all([...])` so the ledger and the graph show it."
+          },
+          {
+            "object": "Promise",
+            "property": "race",
+            "message": "Calls through ctx run one at a time, so nothing races: pick one call, or sleep and then check."
+          },
+          {
+            "object": "Promise",
+            "property": "any",
+            "message": "Calls through ctx run one at a time, so nothing races: pick one call, or sleep and then check."
+          }
+        ],
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "@sanoma-ai/testing",
+                "message": "Fakes and test helpers belong in tests. A workflow must call vendors through ctx, so the policy sees every call."
+              },
+              {
+                "name": "@sanoma-ai/app",
+                "message": "The app starts runs and decides approvals: a workflow could approve itself."
+              },
+              {
+                "name": "@sanoma-ai/workflows",
+                "allowImportNames": [
+                  "defineWorkflow",
+                  "definePolicy",
+                  "allow",
+                  "deny",
+                  "approve",
+                  "approvedFor",
+                  "allowAll",
+                  "mayDecide",
+                  "errorCode",
+                  "z"
+                ],
+                "allowTypeImports": true,
+                "message": "A workflow or policy imports only these and types from @sanoma-ai/workflows: the rest (SanomaClient, startWorker, the ledger stores, config helpers) could start runs, approve its own approvals, forge the ledger or read credentials. Ask for approval with `ctx.approval`."
+              }
+            ],
+            "patterns": [
+              {
+                "group": [
+                  "@sanoma-ai/connector-*/fake",
+                  "@sanoma-ai/connector-*/driver",
+                  "@sanoma-ai/workflows/describe",
+                  "@sanoma-ai/workflows/fake",
+                  "@sanoma-ai/workflows/plugin",
+                  "@sanoma-ai/workflows/scenario",
+                  "@sanoma-ai/workflows/scenarios"
+                ],
+                "message": "A workflow must call vendors through ctx, so the policy sees every call: import the connector itself, `@sanoma-ai/connector-<vendor>`."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": ["resources/**"],
+      "jsPlugins": ["./dist/plugin.js"],
+      "rules": { "sanoma/data-file": "error" }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@sanoma-ai/workflows",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Business processes as TypeScript functions, run durably on DBOS",
+  "keywords": [
+    "approvals",
+    "business-as-code",
+    "dbos",
+    "durable-execution",
+    "sanoma",
+    "workflows"
+  ],
+  "homepage": "https://github.com/Sanoma-AI/sanoma/tree/main/packages/workflows#readme",
+  "bugs": "https://github.com/Sanoma-AI/sanoma/issues",
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sanoma-AI/sanoma.git",
+    "directory": "packages/workflows"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/AGENTS.md",
+    "oxlint.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./describe": {
+      "types": "./dist/describe.d.ts",
+      "default": "./dist/describe.js"
+    },
+    "./fake": {
+      "types": "./dist/fake.d.ts",
+      "default": "./dist/fake.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./resources": {
+      "types": "./dist/secret.d.ts",
+      "default": "./dist/secret.js"
+    },
+    "./scenario": {
+      "types": "./dist/scenario.d.ts",
+      "default": "./dist/scenario.js"
+    },
+    "./scenarios": {
+      "types": "./dist/scenarios.d.ts",
+      "default": "./dist/scenarios.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "default": "./dist/shared.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cucumber/cucumber": "13.3.0",
+    "@cucumber/cucumber-expressions": "^20.1.0",
+    "@cucumber/messages": "^34.2.1",
+    "@cucumber/query": "16.1.1",
+    "@dbos-inc/dbos-sdk": "^5.2.11",
+    "@faker-js/faker": "^10.6.0",
+    "oxc-parser": "^0.153.0",
+    "oxfmt": "^0.72.0",
+    "pg": "^8.23.1",
+    "randexp": "^0.5.3",
+    "zod-schema-faker": "^2.1.2"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.23.1",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4"
+  },
+  "engines": {
+    "node": "24 || >=26"
+  },
+  "//": "randexp is a dependency only because zod-schema-faker, which makes up scenario inputs, needs it as a peer.",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "watch": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
+  }
 }

package/src/apply-steps.ts

@@ -0,0 +1,110 @@
+import { join, relative, sep } from "node:path";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import type { ApplyDeclared, ApplySteps, PlannedCall } from "./apply.ts";
+import { decide } from "./call.ts";
+import type { Approver } from "./define.ts";
+import { type Binding, type Bindings, diffLockfiles, LOCKFILE, readLockfile, writeLockfile } from "./lockfile.ts";
+import { currentRun, type Run } from "./run.ts";
+import { APPLY_WORKFLOW } from "./shared.ts";
+
+// 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 = (): Run => {
+  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: string): Promise<Bindings | undefined> {
+  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 as { bindings: Bindings }).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: string,
+  root: string | undefined,
+  read: () => Promise<Omit<ApplyDeclared, "rebinds">>,
+): ApplySteps {
+  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: PlannedCall[]) =>
+      DBOS.runStep(
+        async (): Promise<Approver | undefined> => {
+          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: string, binding: Binding | undefined, message: string) => {
+      const run = runNow();
+      if (run.sandbox !== undefined || root === undefined) return { written: false };
+      const { source } = run.state;
+      const { revision } = await DBOS.runStep(
+        async (): Promise<{ bindings: Bindings; revision?: string }> => {
+          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 }) };
+    },
+  };
+}