@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/define.ts

@@ -0,0 +1,285 @@
+import { fileURLToPath } from "node:url";
+import { getCallSites } from "node:util";
+import { z } from "zod";
+import { isOp, type Op } from "./op.ts";
+import { approverLabel } from "./shared.ts";
+
+/**
+ * Who is acting: the person or service that starts a run or decides an approval. `id` is
+ * whatever the deployment identifies people by; `groups` are the roles it vouches for.
+ */
+export interface Principal {
+  id: string;
+  groups?: string[];
+}
+
+export const Principal: z.ZodType<Principal> = z.object({
+  id: z.string().regex(/\S/, "id must not be blank"),
+  groups: z.array(z.string()).optional(),
+});
+
+export type Builtin = "approval" | "sleep" | "all";
+export type Use = Op | Builtin;
+
+/** Who may decide an approval: one person, by `Principal.id`, or anyone in a group, by `Principal.groups`. */
+export type Approver = string | { group: string };
+
+export const Approver: z.ZodType<Approver> = z.union(
+  [z.string().regex(/\S/), z.object({ group: z.string().regex(/\S/) })],
+  { error: 'needs an approver: a name, or { group: "name" }' },
+);
+
+/** Why `by` may not decide the approval, naming who may. */
+export const notApprover = ({ approver }: Pick<ApprovalState, "approver">, by: Principal): string =>
+  typeof approver === "string"
+    ? `${by.id} is not the approver; ${approverLabel(approver)} is`
+    : `${by.id} is not in ${approverLabel(approver)}`;
+
+/** True when the two name the same approver: the same id, or the same group. */
+export const sameApprover = (a: Approver, b: Approver): boolean =>
+  typeof a === "string" || typeof b === "string" ? a === b : a.group === b.group;
+
+const notOps = "covers must be a list of operations";
+
+/** `covers` as given (operations), parsed to their ids. */
+export const Covers = z
+  .array(
+    z.object({ id: z.string() }, { error: notOps }).transform((op) => op.id),
+    { error: notOps },
+  )
+  .optional();
+
+export interface ApprovalRequest {
+  /** Who must approve: a person's id, or `{ group }` for anyone in it. Phase 4 replaces this with a Cedar decision. */
+  approver: Approver;
+  /**
+   * The operations the approval stands for, so a policy can let their calls through once it
+   * is approved (`a.covers.includes(op.id)`). None unless given.
+   */
+  covers?: Op[];
+  links?: string[];
+  details?: string;
+}
+
+/**
+ * Checks a `ctx.approval` request as a workflow may give it, so the UI and the ledger get what
+ * the types say, and turns `covers` into op ids.
+ */
+export const ApprovalRequestSchema = z.object(
+  {
+    approver: Approver,
+    covers: Covers,
+    links: z.array(z.string(), { error: "links must be a list of strings" }).optional(),
+    details: z.string({ error: "details must be a string" }).optional(),
+  },
+  { error: "needs a request: { approver, covers?, links?, details? }" },
+);
+
+/** One approval in a run, as the run sees it. Published as the run's "approvals" event. */
+export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
+  id: string;
+  title: string;
+  /** Who asked: the workflow (`ctx.approval`), or the policy holding an operation call. */
+  requestedBy: "workflow" | "policy";
+  /**
+   * The operations the approval stands for, by id. A policy hold covers the call it held and
+   * any `covers` the policy added; a workflow's approval covers the `covers` it named, or none.
+   */
+  covers: string[];
+  /** For a policy request: the operation call held, by op id. */
+  op?: string;
+  /** For a policy request: the ledger `seq` of the call held, which its `op.called` record has. */
+  opSeq?: number;
+  /** For a policy request: the held call's input. */
+  input?: unknown;
+  status: "pending" | "approved" | "rejected";
+  requestedAt: number;
+  decidedBy?: string;
+  decidedAt?: number;
+  note?: string;
+  /** The `id` of the decision message the run decided with, when it had one. */
+  decidedWith?: string;
+  /**
+   * Messages that were ignored: decisions sent by someone who may not decide the approval,
+   * and messages that were not a decision. `by` is the sender, when the message named one, and
+   * `id` the decision message's own, when it had one.
+   */
+  refused: { by?: string; id?: string; at: number; reason: string }[];
+}
+
+export interface ApprovalResult {
+  approvedBy: string;
+  at: number;
+  note?: string;
+}
+
+/**
+ * How long `ctx.sleep` waits: until a time (an ISO 8601 date-time with an offset, such as
+ * `2026-10-07T09:00:00Z`, or epoch milliseconds), or for a duration whose parts add up. A time
+ * already past waits not at all.
+ */
+export type SleepRequest =
+  | { until: string | number }
+  | { ms?: number; seconds?: number; minutes?: number; hours?: number; days?: number };
+
+const time = "must be an ISO 8601 date-time with an offset, such as 2026-10-07T09:00:00Z, or epoch milliseconds";
+const duration = z.number({ error: "must be a number" }).nonnegative("must not be negative").optional();
+
+/** Checks a `ctx.sleep` request that names a time. */
+export const SleepUntil = z.strictObject({
+  until: z.union([z.iso.datetime({ offset: true, error: time }), z.number({ error: time })], { error: time }),
+}) satisfies z.ZodType<SleepRequest>;
+
+/** Checks a `ctx.sleep` request that names a duration. */
+export const SleepFor = z.strictObject({
+  ms: duration,
+  seconds: duration,
+  minutes: duration,
+  hours: duration,
+  days: duration,
+}) satisfies z.ZodType<SleepRequest>;
+
+/** Checks a `ctx.all` argument: a list of functions, each one member. */
+export const AllMembers = z.array(
+  z.custom<() => unknown>((m) => typeof m === "function", "each member must be a function, such as () => ctx.…"),
+  { error: "needs a list of functions: ctx.all([() => …, () => …])" },
+);
+
+/**
+ * What a step is called, beside its operation: `ctx.ghost.post.create(input, { name: "Draft" })`,
+ * `ctx.sleep({ days: 1 }, { name: "Wait a day" })`. A string literal, or a top-level `const` of
+ * the workflow's file holding one, so the outline reads it. Without one, a call is named by its
+ * operation's id, a sleep `Sleep`; an approval by its title. Names are unique in a workflow, so a
+ * workflow that calls one operation twice names the calls.
+ */
+export interface StepOptions {
+  name?: string;
+}
+
+type OpsOf<U extends readonly Use[]> = Extract<U[number], Op>;
+
+type CtxOps<O extends Op> = {
+  readonly [V in O["vendor"]]: {
+    readonly [R in Extract<O, { vendor: V }>["resource"]]: {
+      readonly [N in Extract<O, { vendor: V; resource: R }>["name"]]: Extract<
+        O,
+        { vendor: V; resource: R; name: N }
+      > extends Op<any, any, any, infer I, infer Out>
+        ? (input: I, options?: StepOptions) => Promise<Out>
+        : never;
+    };
+  };
+};
+
+interface ApprovalCtx {
+  /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection. */
+  approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
+}
+
+interface SleepCtx {
+  /** Waits, durably, until a time or for a duration. Survives worker restarts. */
+  sleep(request: SleepRequest, options?: StepOptions): Promise<void>;
+}
+
+interface AllCtx {
+  /**
+   * Runs the members one after another, in order, and returns their outputs in that order. It
+   * declares a fan-out for the ledger and the graph; it adds no concurrency. The first member
+   * that throws stops the group with its error, and later members never run. Not nestable.
+   */
+  all<const T extends readonly (() => Promise<unknown>)[]>(
+    members: T,
+  ): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>> }>;
+}
+
+interface BaseCtx {
+  /** The current time, recorded so replays see the same value. Use instead of `Date.now()`. */
+  now(): Promise<number>;
+  readonly runId: string;
+}
+
+export type Ctx<U extends readonly Use[]> = BaseCtx &
+  CtxOps<OpsOf<U>> &
+  ("approval" extends U[number] ? ApprovalCtx : unknown) &
+  ("sleep" extends U[number] ? SleepCtx : unknown) &
+  ("all" extends U[number] ? AllCtx : unknown);
+
+/**
+ * A schema as JSON Schema (draft 2020-12). By default it describes what a caller sends
+ * (`io: "input"`: defaults stay optional); `io: "output"` describes what parsing returns.
+ * What JSON Schema can't express is left open. Throws when zod can't convert the schema at all.
+ */
+export function jsonSchemaOf(
+  schema: z.ZodType,
+  io: "input" | "output" = "input",
+  refs?: ReadonlyMap<unknown, string>,
+): Record<string, unknown> {
+  return z.toJSONSchema(schema, {
+    io,
+    target: "draft-2020-12",
+    unrepresentable: "any",
+    // A schema `refs` names, inside another, becomes a `$ref` to it (a resource type's state).
+    ...(refs?.size && {
+      override: ({ zodSchema, jsonSchema, path }) => {
+        const ref = path.length > 0 ? refs.get(zodSchema) : undefined;
+        if (ref === undefined) return;
+        for (const key of Object.keys(jsonSchema)) delete (jsonSchema as Record<string, unknown>)[key];
+        Object.assign(jsonSchema, { $ref: ref });
+      },
+    }),
+  });
+}
+
+export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
+  readonly kind: "workflow";
+  readonly name: string;
+  readonly title?: string;
+  readonly trigger: "manual";
+  readonly input: S;
+  /** Every operation and built-in the workflow may call. `ctx` is built from this list and nothing else. */
+  readonly uses: U;
+  readonly run: (ctx: Ctx<U>, input: z.output<S>) => Promise<unknown>;
+  /**
+   * The file that defined it, absolute. Set by defineWorkflow from its call site: the outline is
+   * read from it, the worker holds each run to that outline, and the app shows it as the code view.
+   */
+  readonly file: string;
+}
+
+/** The ids of the operations a workflow `uses`, in the order declared. */
+export const opIdsOf = (wf: Pick<WorkflowDefinition, "uses">): string[] => wf.uses.filter(isOp).map((op) => op.id);
+
+export function defineWorkflow<const U extends readonly Use[], S extends z.ZodType>(
+  def: Omit<WorkflowDefinition<U, S>, "kind" | "file">,
+): WorkflowDefinition<U, S> {
+  if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
+    throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
+  }
+  const file = callerFile();
+  if (file === undefined) {
+    throw new Error(
+      `Workflow "${def.name}" was defined from code with no file (an eval, or a bundle without one): ` +
+        "its outline is read from the file, and a run is held to the outline",
+    );
+  }
+  return Object.freeze({ kind: "workflow", ...def, file });
+}
+
+/**
+ * The file of the code that called the function calling this one (`defineWorkflow`'s caller),
+ * from V8's call sites, as a path; undefined where there is none.
+ */
+export function callerFile(): string | undefined {
+  // Frame 0 is this function, frame 1 its caller, frame 2 theirs: by index, since a bundle may hold all three.
+  return scriptPath(getCallSites(3)[2]?.scriptName);
+}
+
+/** A V8 script name (a `file:` URL for a module, a path for a script) as a path; undefined for none. */
+export function scriptPath(script: string | undefined): string | undefined {
+  if (!script?.startsWith("file:")) return script || undefined;
+  try {
+    return fileURLToPath(script);
+  } catch {
+    return undefined;
+  }
+}

package/src/describe.ts

@@ -0,0 +1,282 @@
+import type { z } from "zod";
+import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
+import { resolveConfig, type SanomaConfig } from "./config.ts";
+import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
+import { lintWorkflow } from "./lint.ts";
+import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
+import { type Outline, outlineWithSource } from "./outline.ts";
+import { allowAll, policyOpOf } from "./policy.ts";
+import { type ResourceFields, resourceTypesOf } from "./resource.ts";
+import { type DataFiles, type DeclaredResource, readDataFiles, type ResourceProblem } from "./resources.ts";
+import { BUILT_IN_WORKFLOWS } from "./shared.ts";
+
+// `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
+export { outlineWorkflow, type Outline, type OutlineNode, type Span } from "./outline.ts";
+// The reader parses data files with oxc-parser too.
+export type { LintProblem } from "./ast.ts";
+export {
+  readDataFiles,
+  readResources,
+  type DataFiles,
+  type DeclaredResource,
+  type ResourceProblem,
+} from "./resources.ts";
+// The writer: setting a resource's fields in its data file, and rendering a new one.
+export { formatOptions, renderDataFile, setFields, type DataFileContent } from "./writer.ts";
+export { Reference, type DataValue } from "./datafile.ts";
+export {
+  LOCKFILE,
+  readLockfile,
+  serializeLockfile,
+  writeLockfile,
+  diffLockfiles,
+  type Binding,
+  type Bindings,
+  type Rebind,
+} from "./lockfile.ts";
+// The apply workflow's plan and report, which the app renders.
+export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
+
+/** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
+export interface WorkflowEntry {
+  name: string;
+  title?: string;
+  trigger: "manual";
+  /**
+   * Set for a workflow the runtime adds itself, `drift` or `apply`, rather than the config: a label. It
+   * starts like any other.
+   */
+  builtin?: true;
+  /** The input, as JSON Schema (draft 2020-12), from the zod schema. */
+  input: Record<string, unknown>;
+  /** Operation ids the workflow may call, in the order declared. */
+  ops: string[];
+  /** Built-ins the workflow may call. */
+  builtins: Builtin[];
+  /** The file that defined it, absolute. */
+  file: string;
+  /** What its `run` calls, in order, read from its file (`outlineWorkflow`), which the worker holds its runs to. */
+  outline: Outline;
+  /**
+   * What is wrong in its file, by position: what `lintWorkflow` finds (syntax, an import a
+   * workflow may not make, `instanceof` against the runtime's error classes, what the outline
+   * cannot draw in each `run`), read the one way the outline is, so a check sees what the
+   * worker refuses; and, at 1:1, an outline error that is the file's (it cannot be read, or holds
+   * no workflow of this name). A file defining several workflows gives each its problems. Empty
+   * for the built-in `drift`, which the package's tests hold to the lint.
+   */
+  problems: LintProblem[];
+  /**
+   * The text the outline's spans index into: the workflow's file, with `\n` line endings.
+   * Absent only when the outline is `{ error }`. Whole files: a server may keep it from clients.
+   */
+  source?: string;
+}
+
+/** What an operation is, read from its connector: enough to badge it and show its contract. */
+export interface OpEntry {
+  id: string;
+  vendor: string;
+  resource: string;
+  name: string;
+  effect: Effect;
+  idempotent: boolean;
+  description?: string;
+  /** How a scenario's steps name it: Cucumber expressions over its input's fields. */
+  phrases?: { given?: string; expect?: string };
+  /** What a call sends, as JSON Schema (`io: "input"`: fields with defaults are optional). */
+  input: Record<string, unknown>;
+  /** What a call returns once its schema has parsed the vendor's reply (`io: "output"`). */
+  output: Record<string, unknown>;
+}
+
+/** Who a vendor is, from its connector's `VendorInfo`: enough to name it, show its logo and link to its connector. */
+export interface VendorEntry {
+  /** The connector's `title`, else the vendor's id. */
+  title: string;
+  /** The logo as `data:image/svg+xml` URLs, for an `<img>`: `dark` is for dark backgrounds. */
+  logo?: { src: string; dark?: string };
+  /** The connector's npm package name. */
+  package?: string;
+  /** The connector package's `homepage` from its package.json: where its code and README are, as an https URL. */
+  homepage?: string;
+  /** Whether the vendor's connector attaches a fake (`withSetup`), for sandbox runs. */
+  fake: boolean;
+}
+
+/** A resource type a connector declares with `defineResource`. */
+export interface ResourceTypeEntry {
+  /** `<vendor>.<type>`, such as `github.repository`. */
+  id: string;
+  vendor: string;
+  type: string;
+  title: string;
+  /** How a declared resource's identity is made, such as `name` or `repository_id:pattern`; absent when it is found only by its binding. */
+  identity?: string;
+  /** Its flagged fields, by dotted path. */
+  fields: ResourceFields;
+  /**
+   * Its state, as a read returns it, as JSON Schema (`io: "output"`), with `$id`
+   * `sanoma:resource-type/<id>`: the operations' contracts `$ref` it instead of repeating it.
+   */
+  schema: Record<string, unknown>;
+  /** Its operations' ids, sorted: `<id>.import` and `<id>.read`, and for a writable type its change operations. */
+  ops: string[];
+}
+
+/**
+ * A plain-JSON description of what a config can do: its workflows, the operations they call,
+ * and whether a policy gates them. The app server builds it from the config and sends it to the
+ * browser, so the UI shows exactly what the worker enforces. Never written by hand.
+ */
+export interface ConfigDescription {
+  appName: string;
+  /** The application version runs started now are stamped with. */
+  version: string;
+  workflows: WorkflowEntry[];
+  ops: OpEntry[];
+  /** Every vendor the operations are from, by its id (an `OpEntry`'s `vendor`). */
+  vendors: Record<string, VendorEntry>;
+  /** The resource types the connectors declare, by `id`. */
+  resourceTypes: ResourceTypeEntry[];
+  /**
+   * The resources the data files under `resources/` declare, by file and then in file order,
+   * less any with a problem and any that names one.
+   */
+  resources: DeclaredResource[];
+  /** Each binding in the lockfile (`LOCKFILE`) whose key no data file declares, as `readDataFiles` reports it. */
+  orphans: DataFiles["orphans"];
+  /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
+  problems: ResourceProblem[];
+  /** `defined` is false for `allowAll`. */
+  policy: { defined: boolean; version?: string };
+}
+
+/**
+ * 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: SanomaConfig): ConfigDescription {
+  const resolved = resolveConfig(config);
+  const vendors: Record<string, VendorEntry> = {};
+  // 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<z.ZodType, string>([...resources].map(([id, r]) => [r.schema, resourceTypeUri(id)]));
+  const resourceTypes: ResourceTypeEntry[] = [...resources]
+    .map(([id, { vendor, type, title, identity, fields, schema, ops }]) => ({
+      id,
+      vendor,
+      type,
+      title,
+      identity,
+      fields,
+      schema: { $id: resourceTypeUri(id), ...toJsonSchema(schema, `${id} state`, "output") },
+      ops: Object.keys(ops)
+        .map((name) => `${id}.${name}`)
+        .toSorted(),
+    }))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+
+  const ops: OpEntry[] = [...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: SourceFile) => lintWorkflow(file));
+  const workflows: WorkflowEntry[] = [...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 builtin = BUILT_IN_WORKFLOWS.has(wf.name);
+    const problems = builtin
+      ? []
+      : [
+          ...(typeof file === "string" ? [] : lint(file)),
+          ...(own ? [{ line: 1, column: 1, message: outline.error }] : []),
+        ];
+    return {
+      name: wf.name,
+      title: wf.title,
+      trigger: wf.trigger,
+      ...(builtin && { builtin: true as const }),
+      input: toJsonSchema(wf.input, `${wf.name} input`, "input"),
+      ops: opIdsOf(wf),
+      builtins: (wf.uses as Use[]).filter((u): u is Builtin => 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,
+    orphans: dataFiles.orphans,
+    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<A, R>(fn: (arg: A) => R): (arg: A) => R {
+  const seen = new Map<A, R>();
+  return (arg) => {
+    if (!seen.has(arg)) seen.set(arg, fn(arg));
+    return seen.get(arg)!;
+  };
+}
+
+const svgDataUrl = (svg: string) => `data:image/svg+xml,${encodeURIComponent(svg.trim())}`;
+
+const vendorEntry = (id: string, info: VendorInfo | undefined, fake: boolean): VendorEntry => ({
+  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: string) => `sanoma:resource-type/${id}`;
+
+function toJsonSchema(
+  schema: z.ZodType,
+  what: string,
+  io: "input" | "output",
+  refs?: ReadonlyMap<unknown, string>,
+): Record<string, unknown> {
+  try {
+    return jsonSchemaOf(schema, io, refs);
+  } catch (e) {
+    throw new Error(`Cannot describe ${what} as JSON Schema: ${(e as Error).message}`, { cause: e });
+  }
+}