@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/lint.js

@@ -0,0 +1,168 @@
+import { basename, dirname, join } from "node:path";
+import { byPosition, childrenOf, parsed } from "./ast.js";
+import { readDataFile } from "./datafile.js";
+import { constsOf, outlineBody, workflowLiterals } from "./outline.js";
+import { inside, nearestDir, RELATIVE } from "./paths.js";
+// From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
+import oxlint from "../oxlint.json" with { type: "json" };
+/**
+ * A workflow must call vendors through `ctx`, so the policy sees every call. These are the
+ * import rules oxlint's built-in rules cannot express; the clock, randomness, the network
+ * and the environment are oxlint's (the package's `oxlint.json`).
+ */
+const THROUGH_CTX = "a workflow must call vendors through ctx, so the policy sees every call";
+/**
+ * The packages the author surface is imported from, each allowing the same names: `sanoma`
+ * re-exports what `@sanoma-ai/workflows` allows (and `z`). Adding one here accepts it.
+ */
+const AUTHOR_PACKAGES = ["@sanoma-ai/workflows", "sanoma"];
+/** The packages a workflow may import from at all: the author packages, connectors and zod. */
+const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connector-[a-z0-9-]+", "zod"].join("|")})$`);
+/** Packages refused by name, with the reason. */
+const REFUSED_PACKAGES = [
+    [/^@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\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
+];
+/**
+ * What a workflow or policy may import from an author package, besides types: the one list,
+ * `allowImportNames` of oxlint.json's `@sanoma-ai/workflows` entry (`sanoma`'s generated
+ * `oxlint.json` derives its own entry from it). Everything else is
+ * refused: the client, the worker and the app could start runs or approve the run's own
+ * approvals, a ledger store could forge the audit record (a store keeps the first record per
+ * id), and config helpers can read credentials.
+ */
+const WORKFLOW_IMPORTS = restrictedImports(oxlint).find((p) => p.name === "@sanoma-ai/workflows")?.allowImportNames ?? [];
+const ALLOWED_NAMES = new Set(WORKFLOW_IMPORTS);
+const NOT_ALLOWED = `a workflow or policy imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
+    `${AUTHOR_PACKAGES.join(" or ")}: the rest could start runs, approve its own approvals, forge the ledger or read credentials`;
+/**
+ * Error classes a run must not test with `instanceof`: on a replay DBOS rethrows a serialized
+ * copy, which is no instance of them, so a branch on it goes another way than the first time
+ * and the run's steps fall out of step. Read the code with `errorCode(err)` instead.
+ */
+const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
+export function lintWorkflow(input, path) {
+    const filename = typeof input === "string" ? path : input.file;
+    const read = typeof input === "string" ? parsed(input, filename ?? "workflow.ts") : input;
+    const { program, at } = read;
+    const problems = [...read.problems];
+    const root = filename === undefined ? undefined : nearestDir(filename, ["workflows", "policies"]);
+    const checkSource = (node) => {
+        const spec = node.source.value;
+        const refusal = whyRefused(spec, filename, root);
+        if (refusal) {
+            problems.push({ ...at(node.source.start), message: `import "${spec}" is not allowed in a workflow: ${refusal}` });
+            return;
+        }
+        if (!AUTHOR_PACKAGES.includes(spec))
+            return;
+        if (node.type === "ExportAllDeclaration") {
+            problems.push({
+                ...at(node.start),
+                message: `export * from "${spec}" is not allowed in a workflow: it would re-export what a workflow may not import`,
+            });
+        }
+        for (const s of node.specifiers ?? []) {
+            if (s.type === "ImportNamespaceSpecifier") {
+                problems.push({
+                    ...at(s.start),
+                    message: `import * from "${spec}" is not allowed in a workflow: import the names you use, so the rest stays out`,
+                });
+                continue;
+            }
+            // `import type { X }`, `import { type X }` and `export type { X }` bring in no values.
+            if (node.importKind === "type" ||
+                node.exportKind === "type" ||
+                s.importKind === "type" ||
+                s.exportKind === "type") {
+                continue;
+            }
+            // What the module exports under: `imported` for an import, `local` for a re-export.
+            const named = s.imported ?? s.local;
+            const imported = s.type === "ImportDefaultSpecifier" ? "default" : (named?.name ?? named?.value);
+            if (!ALLOWED_NAMES.has(imported)) {
+                problems.push({ ...at(s.start), message: `${imported} is not allowed in a workflow: ${NOT_ALLOWED}` });
+            }
+        }
+    };
+    const visit = (node) => {
+        if (!node)
+            return;
+        if ((node.type === "ImportDeclaration" ||
+            node.type === "ExportNamedDeclaration" ||
+            node.type === "ExportAllDeclaration") &&
+            node.source) {
+            checkSource(node);
+        }
+        else if (node.type === "ImportExpression") {
+            problems.push({ ...at(node.start), message: "dynamic import is not allowed in a workflow" });
+        }
+        else if (node.type === "BinaryExpression" && node.operator === "instanceof") {
+            checkInstanceof(node);
+        }
+        for (const child of childrenOf(node))
+            visit(child);
+    };
+    // A workflow imports none of these classes, so they are refused by the name they have.
+    const checkInstanceof = (node) => {
+        const right = node.right;
+        const name = right?.type === "Identifier"
+            ? right.name
+            : right?.type === "MemberExpression" && !right.computed
+                ? right.property?.name
+                : undefined;
+        if (name !== undefined && ERROR_CLASSES.has(name)) {
+            problems.push({
+                ...at(node.start),
+                message: `instanceof ${name} is not allowed in a workflow: on a replay DBOS rethrows a copy of the error, ` +
+                    "which is no instance of it, so the run would take another branch; read `errorCode(err)`",
+            });
+        }
+    };
+    visit(program);
+    // Each workflow's `run` as the worker reads it when it starts: what the outline cannot draw,
+    // the worker refuses to start with. One reading, so the lint and the worker agree.
+    const outlined = { consts: constsOf(program), source: typeof input === "string" ? input : input.source };
+    for (const { run } of workflowLiterals(program))
+        for (const { start, message } of outlineBody(run, outlined).problems)
+            problems.push({ ...at(start), message });
+    return byPosition(problems);
+}
+/**
+ * Checks a data file under `resources/`: only named imports (a connector's constructors from its
+ * `…/resources` entry, and resources from other data files inside the same `resources/`
+ * directory), `export const <name> = <vendor>.<type>({ … })` with literal fields and names of
+ * declared resources, and `export default [ … ]`. Each message says what to write instead.
+ * It is the subset `readResources` reads (`readDataFile`), without the config: whether the
+ * connector, the type and the values are known is the reader's to say.
+ */
+export function lintResources(source, filename) {
+    const { program, problems, at } = parsed(source, filename);
+    for (const p of readDataFile(program, filename).problems)
+        problems.push({ ...at(p.start), message: p.message });
+    return byPosition(problems);
+}
+/** The `paths` of oxlint.json's `no-restricted-imports` rule. */
+function restrictedImports(config) {
+    // JSON types the rule's [severity, options] as an array of either.
+    return config.overrides.flatMap((o) => "no-restricted-imports" in o.rules
+        ? o.rules["no-restricted-imports"][1].paths
+        : []);
+}
+function whyRefused(spec, filename, root) {
+    if (RELATIVE.test(spec)) {
+        if (filename === undefined || root === undefined || inside(root, join(dirname(filename), spec)))
+            return undefined;
+        const where = basename(root) === "workflows" || basename(root) === "policies" ? `${basename(root)}/` : "this directory";
+        return `it reaches outside ${where}, toward the config and its drivers; ${THROUGH_CTX}`;
+    }
+    for (const [pattern, reason] of REFUSED_PACKAGES)
+        if (pattern.test(spec))
+            return reason;
+    if (ALLOWED_PACKAGE.test(spec))
+        return undefined;
+    return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

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

package/dist/lockfile.d.ts

@@ -0,0 +1,36 @@
+import type { ResourceProblem } from "./resources.ts";
+/** Where the lockfile is, relative to the config's root. */
+export declare const LOCKFILE = "resources/sanoma.lock.json";
+/** Which vendor object a declaration means: its `<vendor>.<type>` and the vendor's stable id for it. */
+export interface Binding {
+    type: string;
+    id: string;
+}
+/** The lockfile's content: by declaration key, `<file>#<export>` (the file relative to the config's root, with `/`). */
+export type Bindings = Record<string, Binding>;
+/**
+ * The lockfile under `root`: no bindings when there is none, and no bindings with a problem when
+ * it is not JSON or not a map of `<file>#<export>` to `{ type, id }`.
+ */
+export declare function readLockfile(root: string): {
+    bindings: Bindings;
+    problems: ResourceProblem[];
+};
+/** The lockfile's text for `bindings`: keys sorted, two-space JSON, a trailing newline, so a diff shows only what changed. */
+export declare function serializeLockfile(bindings: Bindings): string;
+/** Writes the lockfile under `root` whole or not at all: to a file beside it, then renamed over it. Apply only. */
+export declare function writeLockfile(root: string, bindings: Bindings): void;
+/**
+ * One change to the lockfile: a declaration bound for the first time (`bind`, `to`), pointed at
+ * another object (`rebind`, `from` and `to`), or no longer bound (`unbind`, `from`). `type` is
+ * the binding's `<vendor>.<type>`, the new one's for a rebind.
+ */
+export interface Rebind {
+    key: string;
+    type: string;
+    kind: "bind" | "rebind" | "unbind";
+    from?: string;
+    to?: string;
+}
+/** What changed from `before` to `after`, by key, sorted. */
+export declare function diffLockfiles(before: Bindings, after: Bindings): Rebind[];

package/dist/lockfile.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+// The lockfile: which vendor object each declaration means, kept apart from the data files (which
+// hold intent only), as `package-lock.json` is from `package.json`. Only apply writes it.
+/** Where the lockfile is, relative to the config's root. */
+export const LOCKFILE = "resources/sanoma.lock.json";
+const lockfile = z.record(z.string().regex(/^resources\/[^#]+#[^#]+$/), z.strictObject({ type: z.string().regex(/^[^.\s]+\.[^.\s]+$/), id: z.string().min(1) }));
+/**
+ * The lockfile under `root`: no bindings when there is none, and no bindings with a problem when
+ * it is not JSON or not a map of `<file>#<export>` to `{ type, id }`.
+ */
+export function readLockfile(root) {
+    const path = join(root, LOCKFILE);
+    if (!existsSync(path))
+        return { bindings: {}, problems: [] };
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        return { bindings: {}, problems: [{ file: LOCKFILE, message: `not JSON: ${e.message}` }] };
+    }
+    const parsed = lockfile.safeParse(json);
+    if (!parsed.success) {
+        // One line: zod's own spans lines.
+        return {
+            bindings: {},
+            problems: [{ file: LOCKFILE, message: z.prettifyError(parsed.error).replaceAll(/\s*\n\s*/g, " ") }],
+        };
+    }
+    return { bindings: parsed.data, problems: [] };
+}
+/** The lockfile's text for `bindings`: keys sorted, two-space JSON, a trailing newline, so a diff shows only what changed. */
+export function serializeLockfile(bindings) {
+    const sorted = Object.entries(bindings)
+        .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, { type, id }]) => [key, { type, id }]);
+    return `${JSON.stringify(Object.fromEntries(sorted), null, 2)}\n`;
+}
+/** Writes the lockfile under `root` whole or not at all: to a file beside it, then renamed over it. Apply only. */
+export function writeLockfile(root, bindings) {
+    const path = join(root, LOCKFILE);
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, serializeLockfile(bindings));
+        renameSync(temporary, path);
+    }
+    catch (err) {
+        rmSync(temporary, { force: true });
+        throw err;
+    }
+}
+/** What changed from `before` to `after`, by key, sorted. */
+export function diffLockfiles(before, after) {
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].toSorted();
+    return keys.flatMap((key) => {
+        const was = before[key];
+        const now = after[key];
+        if (!now)
+            return was ? [{ key, type: was.type, kind: "unbind", from: was.id }] : [];
+        if (!was)
+            return [{ key, type: now.type, kind: "bind", to: now.id }];
+        if (was.id === now.id && was.type === now.type)
+            return [];
+        return [{ key, type: now.type, kind: "rebind", from: was.id, to: now.id }];
+    });
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/lockfile.js.map

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

package/dist/log.d.ts

@@ -0,0 +1,24 @@
+import type { DLogger } from "@dbos-inc/dbos-sdk";
+/** Shows the messages at `level` and above from now on; an unknown level as `warn`. */
+export declare function setLogLevel(level?: string): void;
+/** Tells the operator what the runtime did, such as loading credentials (never their values); shown at `info`. */
+export declare const info: (message: string) => void;
+/** Tells the operator something went wrong or was skipped, without failing anything; shown at `warn`. */
+export declare const warn: (message: string) => void;
+/**
+ * Runs a workflow's body, as a sandbox run's when `sandbox`: `dbosLogger` then shows none of DBOS's
+ * warnings from inside it (its steps' failed tries among them), nor the error it fails with. A
+ * scenario's fakes fail on purpose; the run's ledger and its status say what happened. The run
+ * fails with a copy of its error (same prototype and properties), made for it, so the same error
+ * object thrown by a live run is still shown.
+ */
+export declare function quietIfSandbox<T>(sandbox: boolean, body: () => Promise<T>): Promise<T>;
+/**
+ * DBOS's logger (`DBOS.setConfig`'s `logger`): its lines at the last `startWorker`'s `logLevel`,
+ * printed as DBOS's own console logger (`DBOSConsoleLogger`) prints them, except a sandbox run's
+ * (`quietIfSandbox`). A live run's failed tries and failure show as they always did. Installed
+ * only while DBOS exports no logs over OTLP: a custom logger replaces that transport.
+ */
+export declare const dbosLogger: DLogger;
+/** A value as JSON, or as a string when it isn't JSON, cut to `max` characters, for a message. */
+export declare function shown(value: unknown, max?: number): string;

package/dist/log.js

@@ -0,0 +1,83 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+// DBOS's levels (winston's), most severe first. A message shows when its level is at or above the
+// last `startWorker`'s `logLevel`, as DBOS's own do: `warn` by default. One threshold for the
+// process, as DBOS's own logger is one per process.
+const LEVELS = ["error", "warn", "info", "http", "verbose", "debug", "silly"];
+const levelsUpTo = (level) => new Set(LEVELS.slice(0, LEVELS.indexOf(level) + 1));
+let visible = levelsUpTo("warn");
+/** Shows the messages at `level` and above from now on; an unknown level as `warn`. */
+export function setLogLevel(level = "warn") {
+    visible = levelsUpTo(LEVELS.includes(level) ? level : "warn");
+}
+const shows = (level) => visible.has(level);
+/** Tells the operator what the runtime did, such as loading credentials (never their values); shown at `info`. */
+export const info = (message) => {
+    if (shows("info"))
+        console.info(`sanoma: ${message}`);
+};
+/** Tells the operator something went wrong or was skipped, without failing anything; shown at `warn`. */
+export const warn = (message) => {
+    if (shows("warn"))
+        console.warn(`sanoma: ${message}`);
+};
+/** Set while a sandbox run's body runs. */
+const sandboxRun = new AsyncLocalStorage();
+/** What sandbox runs failed with: each a copy made for its run (`quietIfSandbox`). */
+const sandboxErrors = new WeakSet();
+/**
+ * Runs a workflow's body, as a sandbox run's when `sandbox`: `dbosLogger` then shows none of DBOS's
+ * warnings from inside it (its steps' failed tries among them), nor the error it fails with. A
+ * scenario's fakes fail on purpose; the run's ledger and its status say what happened. The run
+ * fails with a copy of its error (same prototype and properties), made for it, so the same error
+ * object thrown by a live run is still shown.
+ */
+export function quietIfSandbox(sandbox, body) {
+    if (!sandbox)
+        return body();
+    return sandboxRun.run(true, body).catch((err) => {
+        if (typeof err !== "object" || err === null)
+            throw err;
+        const copy = Object.create(Object.getPrototypeOf(err), Object.getOwnPropertyDescriptors(err));
+        // V8's `stack` accessor reads the original's internal slot, which the copy lacks.
+        if ("stack" in err)
+            Object.defineProperty(copy, "stack", { value: err.stack, writable: true, configurable: true });
+        sandboxErrors.add(copy);
+        throw copy;
+    });
+}
+/**
+ * DBOS's logger (`DBOS.setConfig`'s `logger`): its lines at the last `startWorker`'s `logLevel`,
+ * printed as DBOS's own console logger (`DBOSConsoleLogger`) prints them, except a sandbox run's
+ * (`quietIfSandbox`). A live run's failed tries and failure show as they always did. Installed
+ * only while DBOS exports no logs over OTLP: a custom logger replaces that transport.
+ */
+export const dbosLogger = {
+    info: (entry) => void (shows("info") && console.log(entry)),
+    debug: (entry) => void (shows("debug") && console.debug(entry)),
+    warn(entry) {
+        if (shows("warn") && !sandboxRun.getStore())
+            console.warn(entry);
+    },
+    // DBOS's GlobalLogger passes a string, with the stack in `metadata.stack` and an error in `metadata.error`.
+    error(entry, metadata) {
+        const error = metadata?.error;
+        if (!shows("error") || (typeof error === "object" && error !== null && sandboxErrors.has(error)))
+            return;
+        if (metadata?.stack)
+            console.error(entry, "\n", metadata.stack);
+        else
+            console.error(entry);
+    },
+};
+/** A value as JSON, or as a string when it isn't JSON, cut to `max` characters, for a message. */
+export function shown(value, max = Number.POSITIVE_INFINITY) {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

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