@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/describe.js

@@ -0,0 +1,127 @@
+import { readSource } from "./ast.js";
+import { resolveConfig } from "./config.js";
+import { jsonSchemaOf, opIdsOf } from "./define.js";
+import { DRIFT_WORKFLOW } from "./drift.js";
+import { lintWorkflow } from "./lint.js";
+import { VENDOR } from "./op.js";
+import { outlineWithSource } from "./outline.js";
+import { allowAll, policyOpOf } from "./policy.js";
+import { resourceTypesOf } from "./resource.js";
+import { readDataFiles } from "./resources.js";
+// `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
+export { outlineWorkflow } from "./outline.js";
+export { readDataFiles, readResources, } from "./resources.js";
+/**
+ * Describes a config. Throws what `startWorker` would refuse (see `resolveConfig`), except missing
+ * credentials (`SanomaClient.credentials` gives their statuses) and what is wrong in a workflow's
+ * file, which the worker refuses when it reads the outline: that is data, on each workflow's
+ * entry, as the data files' problems are, `problems`, beside the resources read without any.
+ * Each workflow's file is read and parsed once, however many workflows it defines.
+ */
+export function describeConfig(config) {
+    const resolved = resolveConfig(config);
+    const vendors = {};
+    // A vendor whose operations are split over several connectors is named by the first; its
+    // resource types are every connector's.
+    for (const connector of config.connectors) {
+        const { id, info } = connector[VENDOR];
+        vendors[id] ??= vendorEntry(id, info, resolved.fakes.has(id));
+    }
+    const resources = resourceTypesOf(config.connectors);
+    // Each resource type's state is described once, on its entry, and referenced from its operations.
+    const refs = new Map([...resources].map(([id, r]) => [r.schema, resourceTypeUri(id)]));
+    const resourceTypes = [...resources]
+        .map(([id, { vendor, type, title, identity, fields, schema }]) => ({
+        id,
+        vendor,
+        type,
+        title,
+        identity,
+        fields,
+        schema: { $id: resourceTypeUri(id), ...toJsonSchema(schema, `${id} state`, "output") },
+        ops: [`${id}.import`, `${id}.read`],
+    }))
+        .toSorted((a, b) => a.id.localeCompare(b.id));
+    const ops = [...resolved.ops.values()].map((op) => ({
+        ...policyOpOf(op),
+        idempotent: op.idempotent,
+        description: op.description,
+        ...(op.phrases && { phrases: op.phrases }),
+        input: toJsonSchema(op.input, `${op.id} input`, "input", refs),
+        output: toJsonSchema(op.output, `${op.id} output`, "output", refs),
+    }));
+    ops.sort((a, b) => a.id.localeCompare(b.id));
+    const read = memoised(readSource);
+    const lint = memoised((file) => lintWorkflow(file));
+    const workflows = [...resolved.workflows.values()].map((wf) => {
+        const file = read(wf.file);
+        const { outline, source, found } = outlineWithSource(wf, file);
+        // What the lint does not report: the file unread, or no workflow of this name in it.
+        const own = "error" in outline && !found && (typeof file === "string" || !file.problems.length);
+        const problems = wf.name === DRIFT_WORKFLOW
+            ? []
+            : [
+                ...(typeof file === "string" ? [] : lint(file)),
+                ...(own ? [{ line: 1, column: 1, message: outline.error }] : []),
+            ];
+        return {
+            name: wf.name,
+            title: wf.title,
+            trigger: wf.trigger,
+            ...(wf.name === DRIFT_WORKFLOW && { builtin: true }),
+            input: toJsonSchema(wf.input, `${wf.name} input`, "input"),
+            ops: opIdsOf(wf),
+            builtins: wf.uses.filter((u) => typeof u === "string"),
+            file: wf.file,
+            outline,
+            problems,
+            ...(source === undefined ? {} : { source }),
+        };
+    });
+    workflows.sort((a, b) => a.name.localeCompare(b.name));
+    const dataFiles = readDataFiles(resolved.root, config.connectors, resources);
+    return {
+        appName: resolved.appName,
+        version: resolved.version,
+        workflows,
+        ops,
+        vendors,
+        resourceTypes,
+        resources: dataFiles.resources,
+        problems: dataFiles.problems,
+        policy: {
+            defined: resolved.policy !== allowAll,
+            ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
+        },
+    };
+}
+/** `fn`, called once per argument for as long as the returned function lives. */
+function memoised(fn) {
+    const seen = new Map();
+    return (arg) => {
+        if (!seen.has(arg))
+            seen.set(arg, fn(arg));
+        return seen.get(arg);
+    };
+}
+const svgDataUrl = (svg) => `data:image/svg+xml,${encodeURIComponent(svg.trim())}`;
+const vendorEntry = (id, info, fake) => ({
+    title: info?.title ?? id,
+    ...(info?.logo && {
+        logo: { src: svgDataUrl(info.logo.svg), ...(info.logo.dark && { dark: svgDataUrl(info.logo.dark) }) },
+    }),
+    ...(info?.package && { package: info.package }),
+    ...(info?.homepage && { homepage: info.homepage }),
+    fake,
+});
+/** Where a resource type's state schema is, for a `$ref`. */
+const resourceTypeUri = (id) => `sanoma:resource-type/${id}`;
+function toJsonSchema(schema, what, io, refs) {
+    try {
+        return jsonSchemaOf(schema, io, refs);
+    }
+    catch (e) {
+        throw new Error(`Cannot describe ${what} as JSON Schema: ${e.message}`, { cause: e });
+    }
+}
+//# sourceMappingURL=describe.js.map

package/dist/describe.js.map

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

package/dist/drift.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { type WorkflowDefinition } from "./define.ts";
+import type { Op } from "./op.ts";
+import { type DriftField, type Resource } from "./resource.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
+export type { DriftField } from "./resource.ts";
+export { DRIFT_WORKFLOW } from "./shared.ts";
+/**
+ * How a declared resource compares: `clean` when every declared field holds its declared value,
+ * `drifted` when one does not, `gone` when the vendor has no such object, and `error` when it
+ * could not be read (the vendor's error, a policy denial, or no driver for its type).
+ */
+export type DriftStatus = "clean" | "drifted" | "gone" | "error";
+/** One declared resource in a drift report. */
+export interface DriftResult {
+    /** The resource's id, `<file>#<export>`: `resources/identity/github.ts#website`. */
+    id: string;
+    /** Its type within the vendor, such as `repository`. */
+    type: string;
+    vendor: string;
+    /** Its import id. */
+    name: string;
+    status: DriftStatus;
+    /** The declared fields that differ; empty unless `drifted`. */
+    fields: DriftField[];
+    /** Why it could not be read, for `error`. */
+    error?: string;
+}
+/** The drift workflow's output. */
+export interface DriftReport {
+    /** Epoch milliseconds, by `ctx.now()`. */
+    startedAt: number;
+    /** Epoch milliseconds, by `ctx.now()`. */
+    finishedAt: number;
+    /** What was wrong in the data files when the run read them: their resources are not in `resources`. */
+    problems: ResourceProblem[];
+    /** Each resource the data files declared when the run read them, in their order. */
+    resources: DriftResult[];
+}
+/**
+ * The drift workflow's input: nothing. The run reads the data files itself, so a run says what
+ * they declared when it ran, and no caller can hand it other resources to check.
+ */
+export declare const DriftInput: z.ZodObject<{}, z.core.$strict>;
+/**
+ * What a drift run records of the data files, as its first step: each resource without its
+ * write-only values, and the problems.
+ */
+export interface DriftDeclared {
+    resources: Pick<DeclaredResource, "id" | "vendor" | "type" | "name" | "desired" | "refs">[];
+    problems: ResourceProblem[];
+}
+type State = Record<string, unknown>;
+type ImportOp = Op<string, string, "import", {
+    id: string;
+}, {
+    id: string;
+    gone: boolean;
+    state?: State;
+}>;
+/**
+ * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare (`types`) that has a driver, so its version changes with them, not with the data
+ * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
+ * `declared`, the step that reads the data files.
+ *
+ * A run reads the data files (`declared`, recorded as a step, so a replay checks the same list),
+ * then imports each resource by its import id (its `name`), in the files' order: one vendor call
+ * each. An import that says gone is `gone`. Else the state and the declared fields are compared
+ * by `diffDeclared`, a reference against the state of the resource it names, read in the same run
+ * (so GitHub's node id for a repository counts as its name). A failed call is that resource's
+ * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
+ * ends it.
+ */
+export declare function driftWorkflow(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>, drivers: ReadonlyMap<string, unknown>, declared: () => Promise<DriftDeclared>): WorkflowDefinition<readonly ImportOp[], typeof DriftInput>;

package/dist/drift.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { defineWorkflow } from "./define.js";
+import { isRunControlError } from "./errors.js";
+import { diffDeclared } from "./resource.js";
+import { errorMessage } from "./shared.js";
+export { DRIFT_WORKFLOW } from "./shared.js";
+/**
+ * The drift workflow's input: nothing. The run reads the data files itself, so a run says what
+ * they declared when it ran, and no caller can hand it other resources to check.
+ */
+export const DriftInput = z.object({}).strict();
+/**
+ * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
+ * declare (`types`) that has a driver, so its version changes with them, not with the data
+ * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
+ * `declared`, the step that reads the data files.
+ *
+ * A run reads the data files (`declared`, recorded as a step, so a replay checks the same list),
+ * then imports each resource by its import id (its `name`), in the files' order: one vendor call
+ * each. An import that says gone is `gone`. Else the state and the declared fields are compared
+ * by `diffDeclared`, a reference against the state of the resource it names, read in the same run
+ * (so GitHub's node id for a repository counts as its name). A failed call is that resource's
+ * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
+ * ends it.
+ */
+export function driftWorkflow(types, ops, drivers, declared) {
+    const uses = [...types.keys()].toSorted().flatMap((type) => {
+        const op = ops.get(`${type}.import`);
+        return op && drivers.has(op.id) ? [op] : [];
+    });
+    // Why a resource of each type cannot be read, if it cannot.
+    const unreadable = new Map();
+    for (const type of types.keys()) {
+        if (!uses.some((op) => op.id === `${type}.import`))
+            unreadable.set(type, `no driver for ${type}.import`);
+    }
+    return defineWorkflow({
+        // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+        name: "drift",
+        title: "Check resources for drift",
+        trigger: "manual",
+        input: DriftInput,
+        uses,
+        run: async (ctx) => {
+            const startedAt = await ctx.now();
+            const { resources, problems } = await declared();
+            // Every import first, so a reference compares against what its resource holds now.
+            const found = new Map();
+            for (const { id, vendor, type, name } of resources) {
+                const key = `${vendor}.${type}`;
+                const why = types.has(key) ? unreadable.get(key) : `the config's connectors declare no resource type ${key}`;
+                // An if/else, not a `continue`: the outline draws the import as the way past the error.
+                if (why !== undefined)
+                    found.set(id, { error: why });
+                else {
+                    try {
+                        const out = await ctx[vendor][type].import({ id: name });
+                        found.set(id, out.gone || !out.state ? { gone: true } : { state: out.state });
+                    }
+                    catch (err) {
+                        if (isRunControlError(err))
+                            throw err;
+                        found.set(id, { error: errorMessage(err) });
+                    }
+                }
+            }
+            const results = resources.map(({ id, vendor, type, name, desired, refs }) => {
+                const row = { id, type, vendor, name };
+                const now = found.get(id);
+                if ("error" in now)
+                    return { ...row, status: "error", fields: [], error: now.error };
+                if ("gone" in now)
+                    return { ...row, status: "gone", fields: [] };
+                const resource = types.get(`${vendor}.${type}`);
+                // Each reference, by where it is: the values the vendor may hold there for its resource.
+                const accept = {};
+                for (const [at, target] of Object.entries(refs)) {
+                    const by = resource.fields.references?.[at.replaceAll(/\.\d+(?=\.|$)/g, "")]?.by ?? [];
+                    const named = found.get(target);
+                    if (named && "state" in named)
+                        accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
+                }
+                const fields = diffDeclared(resource, now.state, desired, accept);
+                return { ...row, status: fields.length ? "drifted" : "clean", fields };
+            });
+            return { startedAt, finishedAt: await ctx.now(), problems, resources: results };
+        },
+    });
+}
+//# sourceMappingURL=drift.js.map

package/dist/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAA2B,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAmB,YAAY,EAAiB,MAAM,eAAe,CAAC;AAE7E,OAAO,EAAuB,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAyC7C;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAmBhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAoC,EACpC,GAA4B,EAC5B,OAAqC,EACrC,QAAsC;IAEtC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACzD,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC;QACrC,OAAO,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;IACH,4DAA4D;IAC5D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,SAAS,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,iBAAiB,IAAI,SAAS,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,cAAc,CAAC;QACpB,2GAA2G;QAC3G,IAAI,EAAE,OAAuC;QAC7C,KAAK,EAAE,2BAA2B;QAClC,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,UAAU;QACjB,IAAI;QACJ,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjB,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC;YAClC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC;YACjD,mFAAmF;YACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;YACvC,KAAK,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,EAAE,CAAC;gBACnD,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;gBAChC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,oDAAoD,GAAG,EAAE,CAAC;gBAC7G,wFAAwF;gBACxF,IAAI,GAAG,KAAK,SAAS;oBAAE,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;qBAChD,CAAC;oBACJ,IAAI,CAAC;wBACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAE,CAAC,IAAI,CAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;wBAC3D,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;oBAChF,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,IAAI,iBAAiB,CAAC,GAAG,CAAC;4BAAE,MAAM,GAAG,CAAC;wBACtC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBAC9C,CAAC;gBACH,CAAC;YACH,CAAC;YACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAe,EAAE;gBACvF,MAAM,GAAG,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;gBACvC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;gBAC3B,IAAI,OAAO,IAAI,GAAG;oBAAE,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;gBACrF,IAAI,MAAM,IAAI,GAAG;oBAAE,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;gBACjE,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAE,CAAC;gBACjD,yFAAyF;gBACzF,MAAM,MAAM,GAA8B,EAAE,CAAC;gBAC7C,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBAChD,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;oBACvF,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAChC,IAAI,KAAK,IAAI,OAAO,IAAI,KAAK;wBAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;gBAC7G,CAAC;gBACD,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBAClE,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACzE,CAAC,CAAC,CAAC;YACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAwB,CAAC;QACxG,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,49 @@
+import type { Driver, DriverEnv } from "./op.ts";
+/** One environment variable a driver declares in `env`, and whether its value lets the driver run: never the value. */
+export interface CredentialStatus {
+    /** The variable's name, such as `GHOST_ADMIN_API_KEY`. */
+    name: string;
+    /** Its one-line manual, from its schema's `.describe()`. */
+    description?: string;
+    /** It may be unset. */
+    optional: boolean;
+    /** `missing` when unset or empty; `invalid` when its schema refuses the value. */
+    status: "set" | "missing" | "invalid";
+    /** Why it is `invalid`: the schema's first issue, never the value. */
+    problem?: string;
+    /**
+     * Where the value is from, when there is one: the process environment, which wins, or the
+     * credentials stored with `SanomaClient.setCredential`. Only `SanomaClient.credentials` says.
+     */
+    source?: "environment" | "stored";
+    /** Who set the stored value (`setCredential`'s `by`). */
+    setBy?: string;
+    /** When the stored value was set, as an ISO 8601 time. */
+    setAt?: string;
+}
+/**
+ * Each vendor's driver's `env` (a resolved config's `driversByVendor`), by vendor in the map's
+ * order (a vendor whose driver declares none has no entry), each variable in declared order and
+ * checked against the value `lookup` gives for its name: only the declared names are looked up,
+ * an empty value counts as unset, and a value is never kept. The one walk of the declarations:
+ * the worker, the client and its checks all read them through it.
+ */
+export declare function credentialsOf(drivers: ReadonlyMap<string, Driver>, lookup: (name: string) => string | undefined): Map<string, CredentialStatus[]>;
+/** One driver's `env`, each variable checked against `lookup`'s value, as `credentialsOf` checks it. */
+export declare function statusesOf(env: DriverEnv, lookup: (name: string) => string | undefined): CredentialStatus[];
+/**
+ * Why the vendor's drivers cannot run on `statuses`, as a call to one fails (`startWorker` names
+ * the vendor alone, `unconfiguredSummary`): `<vendor> is not configured: <problems>; <hint>`, a
+ * missing variable (not optional) as `NAME (description)`, an invalid one as `NAME is invalid:
+ * <why>`, never a value. The hint says
+ * where to set them: in the environment when an invalid value is there (the environment wins
+ * over a stored value, so the connector page cannot replace it), else on the connector page.
+ * Undefined when the drivers can run.
+ */
+export declare function unconfigured(vendor: string, statuses: readonly CredentialStatus[]): string | undefined;
+/**
+ * The one line `startWorker` prints for the vendors whose drivers cannot run yet (`vendors`, those
+ * `unconfigured` has a message for) among the config's `total`: their names alone, since a call
+ * to one fails with its own message, and its connector page says the same. Undefined for none.
+ */
+export declare function unconfiguredSummary(vendors: readonly string[], total: number): string | undefined;

package/dist/env.js

@@ -0,0 +1,83 @@
+import { credentialReady } from "./shared.js";
+/**
+ * Each vendor's driver's `env` (a resolved config's `driversByVendor`), by vendor in the map's
+ * order (a vendor whose driver declares none has no entry), each variable in declared order and
+ * checked against the value `lookup` gives for its name: only the declared names are looked up,
+ * an empty value counts as unset, and a value is never kept. The one walk of the declarations:
+ * the worker, the client and its checks all read them through it.
+ */
+export function credentialsOf(drivers, lookup) {
+    const map = new Map();
+    for (const [vendor, { env }] of drivers)
+        if (env)
+            map.set(vendor, statusesOf(env, lookup));
+    return map;
+}
+/** One driver's `env`, each variable checked against `lookup`'s value, as `credentialsOf` checks it. */
+export function statusesOf(env, lookup) {
+    return Object.entries(env.shape).map(([name, schema]) => credentialStatus(name, schema, lookup(name) || undefined));
+}
+/**
+ * Why the vendor's drivers cannot run on `statuses`, as a call to one fails (`startWorker` names
+ * the vendor alone, `unconfiguredSummary`): `<vendor> is not configured: <problems>; <hint>`, a
+ * missing variable (not optional) as `NAME (description)`, an invalid one as `NAME is invalid:
+ * <why>`, never a value. The hint says
+ * where to set them: in the environment when an invalid value is there (the environment wins
+ * over a stored value, so the connector page cannot replace it), else on the connector page.
+ * Undefined when the drivers can run.
+ */
+export function unconfigured(vendor, statuses) {
+    const unready = statuses.filter((c) => !credentialReady(c));
+    if (!unready.length)
+        return undefined;
+    const problems = unready.map((c) => c.status === "invalid"
+        ? `${c.name} is invalid: ${c.problem}`
+        : `${c.name}${c.description ? ` (${c.description})` : ""}`);
+    const inEnvironment = unready.some((c) => c.status === "invalid" && process.env[c.name]);
+    const hint = inEnvironment ? "set in the environment" : "set it on the connector page";
+    return `${vendor} is not configured: ${problems.join(", ")}; ${hint}`;
+}
+/**
+ * The one line `startWorker` prints for the vendors whose drivers cannot run yet (`vendors`, those
+ * `unconfigured` has a message for) among the config's `total`: their names alone, since a call
+ * to one fails with its own message, and its connector page says the same. Undefined for none.
+ */
+export function unconfiguredSummary(vendors, total) {
+    if (!vendors.length)
+        return undefined;
+    return (`${vendors.length} of ${total} connectors not configured yet: ${vendors.join(", ")}; ` +
+        "set their variables on the connector pages or in the environment");
+}
+function credentialStatus(name, schema, value) {
+    const description = descriptionOf(schema);
+    const parsed = value === undefined ? undefined : check(schema, value);
+    const problem = parsed?.problem;
+    return {
+        name,
+        ...(description !== undefined && { description }),
+        optional: check(schema, undefined).success,
+        status: !parsed ? "missing" : parsed.success ? "set" : "invalid",
+        ...(problem !== undefined && { problem }),
+    };
+}
+/**
+ * `schema.safeParse(value)`, with its first issue's message as the problem. A check that throws
+ * (zod lets a `.refine()` or `.transform()` throw) fails without its error, which may carry the value.
+ */
+function check(schema, value) {
+    try {
+        const { success, error } = schema.safeParse(value);
+        return { success, ...(error && { problem: error.issues[0].message }) };
+    }
+    catch {
+        return { success: false, problem: "its check threw" };
+    }
+}
+/** A schema's `.describe()`, also through `.optional()`, `.default()` and `.prefault()` in any order. */
+function descriptionOf(schema) {
+    let s = schema;
+    while (s && !s.description)
+        s = "unwrap" in s ? s.unwrap() : undefined;
+    return s?.description;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,88 @@
+import type { z } from "zod";
+import type { Principal } from "./define.ts";
+declare const CODES: readonly ["policy_denied", "approval_rejected", "not_approver", "no_pending_approval", "already_decided", "run_not_found", "driver_failed", "invalid_input", "run_ended", "run_running", "call_not_in_outline"];
+/**
+ * Why something failed, as a stable string a caller can branch on. Messages are for people
+ * and may change; codes are the contract.
+ */
+export type ErrorCode = (typeof CODES)[number];
+/**
+ * An error with a `code` and plain-JSON `data`, both own enumerable properties, so they survive
+ * the trip through DBOS: a run's error is stored serialized and comes back as a new object that
+ * is not an instance of this class. Read the code with `errorCode`, never `instanceof`.
+ */
+export declare class SanomaError extends Error {
+    readonly code: ErrorCode;
+    readonly data: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, data?: Record<string, unknown>, options?: ErrorOptions);
+}
+/** The error's code, read from its own `code` property, or undefined when it has none of ours. */
+export declare function errorCode(e: unknown): ErrorCode | undefined;
+/**
+ * True when the error says trying again would only repeat it (`retryable: false`), as a
+ * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as
+ * a property, never `instanceof`: the error may come from another copy of this package.
+ */
+export declare const isFinal: (err: unknown) => boolean;
+/** The error and the ones it was caused by, a few deep. */
+export declare function causes(err: unknown): Error[];
+/**
+ * True for a failure that ends the run rather than one call: anything DBOS throws (it cancelled
+ * the run, another process took it over, the worker is shutting down, the run is not
+ * deterministic) and `run_ended` (a call queued after the run's body ended). Looked for in the
+ * error and its causes. A workflow that goes on past a failed call, as `drift` does, rethrows these.
+ */
+export declare const isRunControlError: (err: unknown) => boolean;
+/** Thrown into the run when the policy denies an operation call. The run fails with it. */
+export declare class PolicyDeniedError extends SanomaError {
+    constructor(op: string, reason: string);
+}
+/** Thrown into the run when an approver rejects. The run fails with it. */
+export declare class RejectedError extends SanomaError {
+    /**
+     * @param title The approval's title.
+     * @param by Who rejected it.
+     * @param approvalId The approval's id in the run, such as "approval-2".
+     */
+    constructor(title: string, by: Principal, note: string | undefined, approvalId: string);
+}
+/**
+ * The wrapper, given the original's own `code` and `data` when it has one of our codes, so
+ * `errorCode` reads the same through it: a denied call whose ledger write failed too is still
+ * `policy_denied`.
+ */
+export declare function keepCode<E extends Error>(wrapper: E, original: unknown): E;
+/** A zod issue as the ledger and an API can carry it: no symbols in the path. */
+export interface InputIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/** The value, parsed by the schema, or an `invalid_input` error carrying zod's issues and `data`. */
+export declare function parseOrThrow<T extends z.ZodType>(schema: T, value: unknown, what: string, data?: Record<string, unknown>): z.output<T>;
+/** An `invalid_input` error from zod issues, with the issues in `data` and a one-line message. */
+export declare function invalidInput(what: string, zodIssues: readonly {
+    path: PropertyKey[];
+    message: string;
+    code: string;
+}[], data?: Record<string, unknown>): SanomaError;
+/**
+ * What the ledger keeps of an error. `status`, `vendorCode` and `retryable` are a
+ * `DriverError`'s account of the vendor's answer; `data` is one of the runtime's errors'. Each is
+ * there only when the error has it, and `data`, `status` and `vendorCode` only from those errors.
+ */
+export interface ErrorInfo {
+    code?: ErrorCode;
+    name: string;
+    message: string;
+    /** The vendor's HTTP status, from a `DriverError`. */
+    status?: number;
+    /** The vendor's own error code, from a `DriverError`. */
+    vendorCode?: string;
+    /** Whether trying again could succeed, from a `DriverError` or a ledger store. */
+    retryable?: boolean;
+    /** A `SanomaError`'s `data`: the operation, the approval, the issues. */
+    data?: Record<string, unknown>;
+}
+export declare function errorInfo(err: unknown): ErrorInfo;
+export {};