@sanoma-ai/workflows 0.0.0-stage → 0.1.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/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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"}

package/dist/op.d.ts

@@ -0,0 +1,257 @@
+import type { z } from "zod";
+import type { Fake } from "./fake.ts";
+import type { Steps } from "./steps.ts";
+/**
+ * What an operation does to the outside world. It sets the badge a reviewer
+ * sees and, later, the Cedar action the call is checked against.
+ */
+export type Effect = "read" | "write" | "publish" | "send" | "money" | "access";
+export interface OpSpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    effect: Effect;
+    input: I;
+    output: O;
+    /** Safe to retry: the vendor dedupes repeated calls. Otherwise a failed call stops the run. */
+    idempotent?: boolean;
+    description?: string;
+    /**
+     * The resource instance a call acts on, from its parsed input, such as a post's id. The
+     * policy sees it as `target`, so it can decide per instance. Must be deterministic.
+     *
+     * Its input is typed `any` inside `defineConnector`: TypeScript gives an inline function the
+     * type `Specs` declares, not the one its own spec's schema implies. Annotate it to have it
+     * checked: `target: ({ id }: { id: string }) => \`post/${id}\``.
+     */
+    target?: (input: any) => string;
+    /**
+     * How a scenario says this operation was set up or called, in Gherkin steps: `given` seeds
+     * the fake through it, `expect` expects a call to it. Cucumber expressions whose parameters are
+     * fields of the input, such as `{ given: "a post titled {title} exists" }`.
+     */
+    phrases?: {
+        given?: string;
+        expect?: string;
+    };
+    /**
+     * Top-level fields of its input and output that are the driver's own data, not the vendor's
+     * (a resource type's `handle`): the ledger records each as `"<name>"`, never its value.
+     */
+    opaque?: readonly string[];
+}
+/** One vendor operation, such as `ghost.post.publish`. Declares the contract only; drivers implement it. */
+export interface Op<V extends string = string, R extends string = string, N extends string = string, I = any, O = any> {
+    readonly kind: "op";
+    readonly id: `${V}.${R}.${N}`;
+    readonly vendor: V;
+    readonly resource: R;
+    readonly name: N;
+    readonly effect: Effect;
+    readonly idempotent: boolean;
+    readonly description?: string;
+    /** From the spec: the resource instance a call acts on. */
+    readonly target?: (input: any) => string;
+    /** From the spec: how a scenario's steps name it. */
+    readonly phrases?: {
+        readonly given?: string;
+        readonly expect?: string;
+    };
+    /** From the spec: fields the ledger records by name only. */
+    readonly opaque?: readonly string[];
+    readonly input: z.ZodType<any, I>;
+    readonly output: z.ZodType<O>;
+}
+/**
+ * Where a resource type keeps its brand. A symbol, so `defineConnector` tells a resource type
+ * (`defineResource`) from a group of operations; a registered one (`Symbol.for`), so a copy of
+ * this package reads what another copy made, as `VENDOR`.
+ */
+export declare const RESOURCE: unique symbol;
+/** What `defineConnector` reads of a resource type; `defineResource` makes them. */
+export interface ResourceGroup {
+    readonly [RESOURCE]: true;
+    readonly vendor: string;
+    readonly type: string;
+    readonly ops: Readonly<Record<string, OpSpec>>;
+}
+/** A connector's groups: operations by name, or a resource type, whose operations are `read` and `import`. */
+export type Specs = Record<string, Record<string, OpSpec> | ResourceGroup>;
+/** The operations of one group of `Specs`. */
+export type GroupOps<G> = G extends ResourceGroup ? G["ops"] : G;
+type InputOf<T> = T extends OpSpec<infer I, any> ? I : never;
+type OutputOf<T> = T extends OpSpec<any, infer O> ? O : never;
+/**
+ * Where a connector keeps its vendor. A symbol, so it names no resource: `Object.values` and
+ * `keyof` over a connector see its resources only. A registered one (`Symbol.for`): a process
+ * may load two copies of this package (a connector's peer linked into a sanoma checkout, the
+ * app's from its tarball), and each must read the connectors the other made.
+ */
+export declare const VENDOR: unique symbol;
+export type Connector<V extends string, S extends Specs> = {
+    readonly [R in keyof S & string]: {
+        readonly [N in keyof GroupOps<S[R]> & string]: Op<V, R, N, z.input<InputOf<GroupOps<S[R]>[N]>>, z.output<OutputOf<GroupOps<S[R]>[N]>>>;
+    };
+} & {
+    readonly [VENDOR]: ConnectorVendor<V>;
+};
+/**
+ * The shape of a connector's `[VENDOR]` record. A process may load two builds of this package,
+ * and `resolveConfig` reads only a record of its own shape (`checkConnector`): change it with
+ * the record, so a build refuses a connector another build made in another shape.
+ */
+export declare const CONNECTOR_FORMAT = 1;
+/**
+ * A connector's vendor: its id, who it is (`defineConnector`'s third argument, for a UI), its
+ * resource types, and the driver and fake its package attaches (`withSetup`).
+ */
+export interface ConnectorVendor<V extends string = string> {
+    /** The record's shape (`CONNECTOR_FORMAT`). */
+    readonly format: typeof CONNECTOR_FORMAT;
+    readonly id: V;
+    readonly info?: VendorInfo;
+    /** The resource types among its groups, in the order given. */
+    readonly resources: readonly ResourceGroup[];
+    /** What `withSetup` attached: how the config's resolver makes its driver and its fake. */
+    readonly setup?: ConnectorSetup;
+}
+/**
+ * Who a connector's vendor is, and where the connector lives, for a UI to show beside its
+ * operations. `logo` is the vendor's mark as inline SVG markup (one `<svg>…</svg>` element), and
+ * `dark` its variant for dark backgrounds. The app shows a logo only as an image (a `data:` URL
+ * in an `<img>`), where an SVG's scripts and external references never run or load.
+ */
+export interface VendorInfo {
+    /** The vendor's name as it writes it, such as "Resend". */
+    title?: string;
+    logo?: {
+        svg: string;
+        dark?: string;
+    };
+    /** The connector's npm package name, such as "@sanoma-ai/connector-resend". */
+    package?: string;
+    /** The connector package's `homepage` from its package.json: where its code and README are, as an https URL. */
+    homepage?: string;
+}
+/**
+ * Declares a vendor's operations, grouped by resource: `defineConnector("ghost", { post: { create: {...} } })`.
+ * A group may be a resource type from `defineResource`, under its own `type`, for its `read` and
+ * `import`: `defineConnector("github", { repository }, { package: "@sanoma-ai/connector-github" })`;
+ * it must be of the same vendor, and the connector needs `info.package`, whose `/resources`
+ * entry exports the types for data files.
+ * `info` says who the vendor is and where the connector lives, for a UI:
+ * `{ title: "Resend", logo: { svg }, package: "@sanoma-ai/connector-resend", homepage: "https://…" }`.
+ */
+export declare function defineConnector<const V extends string, const S extends Specs>(vendor: V, specs: S, info?: VendorInfo): Connector<V, S>;
+/**
+ * What the runtime tells a driver about the call it is making. `idempotencyKey` is the same
+ * on every replay and retry of one call (`<runId>:<seq>`), so a driver can hand it to the
+ * vendor, or dedupe on it, and a crash between the vendor's reply and the checkpoint does
+ * not repeat the side effect.
+ */
+export interface CallContext {
+    idempotencyKey: string;
+    runId: string;
+    opId: string;
+    /** 1 on the first try; retries count up (idempotent operations only). */
+    attempt: number;
+}
+export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;
+/**
+ * A vendor's answer that the driver understood. `retryable` tells the runtime whether to try
+ * again (an idempotent operation on a timeout or a 5xx) or to stop (a 4xx). `status` and
+ * `vendorCode` keep what the vendor said, so the ledger and the UI can show it.
+ */
+export declare class DriverError extends Error {
+    readonly code: "driver_failed";
+    readonly retryable: boolean;
+    readonly status?: number;
+    readonly vendorCode?: string;
+    constructor(message: string, options: {
+        retryable: boolean;
+        status?: number;
+        vendorCode?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Whether a vendor's HTTP status is worth retrying: a request timeout (408), a rate limit (429)
+ * or a server error (5xx). It is the runtime's default rule; a driver adds its vendor's
+ * exceptions around it, such as a quota that does not lift in the seconds a retry waits.
+ */
+export declare function retryableStatus(status: number): boolean;
+/**
+ * The environment variables a driver reads, as a Zod object of string schemas keyed by variable
+ * name, such as `z.object({ ACME_API_KEY: z.string().describe("an API key, from Settings, API keys") })`:
+ * each `.describe()` is the variable's one-line manual (what to put there, where to get it),
+ * `.optional()` marks one that may be unset. `resolveConfig` checks it against `process.env` and
+ * never keeps a value. The driver still reads the raw environment when it is called, so a
+ * `.default()` or `.transform()` is not applied to what it reads (use `.optional()` and name the
+ * default in `.describe()`), and a `.refine()` or `.superRefine()` on the object is not evaluated,
+ * only its fields.
+ */
+export type DriverEnv = z.ZodObject<Record<string, z.ZodType<string | undefined, string | undefined>>>;
+/**
+ * Implements a vendor's operations, keyed `"resource.name"`. A driver reads its credentials
+ * from the environment when it is called, never from the config file; `env` declares them.
+ */
+export interface Driver {
+    readonly vendor: string;
+    readonly ops: Readonly<Record<string, DriverFn>>;
+    readonly env?: DriverEnv;
+}
+/**
+ * What a connector package attaches to its connector (`withSetup`), for the config's resolver
+ * to call: the config then names the connector alone, and never a driver, a fake or steps. Any may
+ * be missing: a workflow using an operation of a connector with no driver is refused, and a
+ * connector with no fake has none for sandbox runs.
+ */
+export interface ConnectorSetup {
+    /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
+    driver?: () => Driver;
+    /** Makes a fake of the vendor (`defineFake`): once per sandbox run, its own. */
+    fake?: () => Fake<any, any>;
+    /** The connector's steps for Gherkin tests (`defineSteps`): a config's scenarios and the connector's own features can use them. */
+    steps?: Steps;
+}
+/**
+ * The connector with `setup` laid over what it already carries, as a connector package exports
+ * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A
+ * config that needs a driver made otherwise (another bridge, other options) swaps that one and
+ * keeps the fake: `withSetup(github, { driver: () => githubDriver({ bridge }) })`. The operations
+ * are the same objects, and the type is the connector's. The setup is kept on the connector's
+ * vendor record (`[VENDOR]`), so a spread copy of the connector keeps it.
+ */
+export declare function withSetup<C extends Connector<any, any>>(connector: C, setup: Partial<ConnectorSetup>): C;
+/**
+ * Throws unless `value` is a connector this package can read: one `defineConnector` made, in this
+ * copy of the package or another of the same `CONNECTOR_FORMAT`. One an older build made (its
+ * `VENDOR` an unregistered symbol, or its record without a format) is refused as such.
+ */
+export declare function checkConnector(value: unknown): asserts value is Connector<any, any>;
+/** What `withSetup` attached to a connector: nothing when it attached nothing. */
+export declare const setupOf: (connector: Connector<any, any>) => ConnectorSetup;
+export declare function isOp(x: unknown): x is Op;
+/**
+ * What a driver for a connector must implement: every operation, by resource and name. Each
+ * function gets the input as the operation's schema parses it and returns what its output
+ * schema accepts.
+ */
+export type DriverImpl<S extends Specs> = {
+    [R in keyof S & string]: {
+        [N in keyof GroupOps<S[R]> & string]: DriverFn<z.output<InputOf<GroupOps<S[R]>[N]>>, z.input<OutputOf<GroupOps<S[R]>[N]>>>;
+    };
+};
+/** The ids of a connector's operations, such as `"ghost.post.create" | "ghost.post.publish"`. */
+export type OpIdOf<V extends string, S extends Specs> = {
+    [R in keyof S & string]: {
+        [N in keyof GroupOps<S[R]> & string]: `${V}.${R}.${N}`;
+    }[keyof GroupOps<S[R]> & string];
+}[keyof S & string];
+/**
+ * Implements a connector's operations, typed by its schemas. A driver must be complete: an
+ * operation the connector declares that `impl` leaves out, or one `impl` adds that the
+ * connector doesn't declare, is refused here rather than when a run calls it. `options.env`
+ * declares the environment variables it reads (see `DriverEnv`).
+ */
+export declare function defineDriver<V extends string, S extends Specs>(connector: Connector<V, S>, impl: DriverImpl<S>, options?: {
+    env?: DriverEnv;
+}): Driver;
+export {};