@sanoma-ai/workflows 0.2.0 → 0.4.0

package/src/resource.ts

@@ -24,8 +24,8 @@ export interface ResourceFields {
 
 /** Where a field names another declared resource: see `ResourceFields.references`. */
 export interface FieldReference {
-  /** The `<vendor>.<type>` of the resource it names. */
-  readonly type: string;
+  /** The `<vendor>.<type>` of the resource it names, or the types it may name one of. */
+  readonly type: string | readonly string[];
   /**
    * The fields of that resource's state the vendor may hold here instead of its `name`, such as
    * GitHub's `node_id`: a drift check takes any of their values, read in the same run, as the
@@ -85,6 +85,12 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
    * recreated database looks fine and has lost its data. Default: true for a host, else false.
    */
   stateless?: boolean;
+  /**
+   * True when there is no vendor object behind a declaration: the repo is all there is of it (the
+   * runtime's people, `sanoma.person`). Such a type has no operations, so no driver, and drift and
+   * apply pass its resources by. Default false.
+   */
+  vendorless?: boolean;
   /**
    * Operations apply calls, in order, right after it creates one of its objects and binds it: a
    * Supabase project's health, until it is healthy, then its database URL stored.
@@ -156,12 +162,14 @@ type DeclaringAt<T, R extends References, P extends string> = T extends readonly
     : WithSecrets<T>;
 
 type DeclaringField<V, R extends References, P extends string> = P extends keyof R
-  ? WithSecrets<V> | DeclaredOf<R[P]["type"]>
+  ? V extends readonly (infer I)[]
+    ? (WithSecrets<I> | DeclaredOf<R[P]["type"]>)[]
+    : WithSecrets<V> | DeclaredOf<R[P]["type"]>
   : [Extract<keyof R, `${P}.${string}`>] extends [never]
     ? WithSecrets<V>
     : DeclaringAt<V, R, P>;
 
-type DeclaredOf<Id> = Id extends string ? Declared<Id> : never;
+type DeclaredOf<Id> = Id extends string ? Declared<Id> : Id extends readonly (infer E)[] ? DeclaredOf<E> : never;
 
 const importId = z.string().min(1);
 /** What a driver keeps beside a state (an OpenTofu provider's private data and state version), passed back unchanged. */
@@ -239,6 +247,15 @@ export function isChangeOp(
   );
 }
 
+/**
+ * True for an operation of a declared resource type (`read`, `import`, and a writable type's
+ * `plan` and change operations), which only drift and apply call: by its vendor and resource.
+ */
+export const isResourceOp = (
+  op: { readonly vendor: string; readonly resource: string },
+  types: ReadonlyMap<string, unknown>,
+): boolean => types.has(`${op.vendor}.${op.resource}`);
+
 /**
  * A resource type: call it to declare a resource in a data file, and give it to
  * `defineConnector` as a group, under its `type`: `defineConnector("github", { repository })`.
@@ -250,7 +267,11 @@ export interface Resource<
   W extends boolean = boolean,
 >
   extends
-    Readonly<Required<Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate">>>,
+    Readonly<
+      Required<
+        Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate" | "vendorless">
+      >
+    >,
     Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "afterCreate">> {
   (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
   /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
@@ -259,6 +280,8 @@ export interface Resource<
   readonly writable: W;
   /** True when apply may recreate or replace its objects as routine: they keep no data. */
   readonly stateless: boolean;
+  /** True when there is no vendor object behind it (`ResourceSpec.vendorless`): it has no operations. */
+  readonly vendorless: boolean;
   readonly [RESOURCE]: true;
 }
 
@@ -517,6 +540,8 @@ export function defineResource<
   const writable = (spec.writable ?? false) as W;
   const what: `${V}.${T}` = `${vendor}.${type}`;
   if (host) checkHost(what, host, spec);
+  if (spec.vendorless && (writable || host))
+    throw new Error(`${what}: a vendorless type has no object to change or host`);
   const title = spec.title.toLowerCase();
   const io = opsOf(schema);
   // The policy's `target` for a create: the type, as no object has an id yet.
@@ -572,7 +597,7 @@ export function defineResource<
       opaque,
     },
   } satisfies Specs<S, "read" | "import">;
-  const ops = (writable ? { ...base, ...changeOps } : base) as unknown as ResourceOps<S, W>;
+  const ops = (spec.vendorless ? {} : writable ? { ...base, ...changeOps } : base) as unknown as ResourceOps<S, W>;
 
   const named = new Set(identity?.match(/[A-Za-z_][\w.]*/g));
   const owned = new Set(fields.vendorOwned.filter((path) => !named.has(path)));
@@ -599,8 +624,9 @@ export function defineResource<
         const id = value[DECLARED];
         const wants = references[path];
         if (wants === undefined) throw new Error(`${what}: ${at} takes a value, not a resource (${id} ${value.name})`);
-        if (wants.type !== id)
-          throw new Error(`${what}: ${at} names a resource of type ${wants.type}, not ${id} (${value.name})`);
+        const types = [wants.type].flat();
+        if (!types.includes(id))
+          throw new Error(`${what}: ${at} names a resource of type ${types.join(" or ")}, not ${id} (${value.name})`);
         if (value.name === undefined)
           throw new Error(`${what}: ${at} names a ${id}, which has no identity to name it by`);
         refs[at] = `${id}:${value.name}`;
@@ -652,6 +678,7 @@ export function defineResource<
     writable,
     ...(host && { host }),
     stateless: spec.stateless ?? host !== undefined,
+    vendorless: spec.vendorless ?? false,
     ...(spec.afterCreate && { afterCreate: spec.afterCreate }),
     ops,
     // A symbol, so `defineConnector` tells a resource type from a group of operations.

package/src/resources.ts

@@ -1,13 +1,31 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { parsed } from "./ast.ts";
-import { rootOf, type SanomaConfig } from "./config.ts";
-import { type DataFile, type DataFileExport, type DataValue, readDataFile, Reference } from "./datafile.ts";
+import {
+  type DataFile,
+  type DataFileExport,
+  type DataValue,
+  readDataFile,
+  Reference,
+  SECRET_ENTRIES,
+} from "./datafile.ts";
 import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
+import { filesUnder } from "./paths.ts";
+import { peopleConnector } from "./person.ts";
 import type { Span } from "./outline.ts";
 import { type Declared, type Resource, resourceTypesOf } from "./resource.ts";
-import { problemLine } from "./shared.ts";
+import { Principal } from "./define.ts";
+import { NotAdmittedError } from "./errors.ts";
+import {
+  AGENTS,
+  declaresPeople,
+  type PeopleResource,
+  personOf,
+  principalOf,
+  problemLine,
+  RUNTIME_AGENTS,
+} from "./shared.ts";
 
 /** A resource a data file declares, as read from the file without running it. */
 export interface DeclaredResource {
@@ -34,6 +52,22 @@ export interface DeclaredResource {
   refs: Record<string, string>;
 }
 
+/**
+ * A collection `resources/data.ts` declares, as read without running it: where it is, for the
+ * Resources page. Its fields are the collection's own (`describeConfig`'s `collections`), from
+ * the same file, which the runtime imports.
+ */
+export interface DeclaredCollection {
+  /** `<file>#<export>`, as a resource's: `resources/data.ts#outbound`. */
+  id: string;
+  /** `resources/data.ts`. */
+  file: string;
+  /** The collection's name, its operations' middle segment (`data.<name>.get`). */
+  name: string;
+  /** Its `export const` statement, as UTF-16 offsets into the file's text. */
+  span: Span;
+}
+
 /** Something wrong in the data files, or in finding them. */
 export interface ResourceProblem {
   /**
@@ -56,22 +90,110 @@ export interface DataFiles {
   bindings: Bindings;
   /** Each binding whose key no data file declares, by key. */
   orphans: (Binding & { key: string })[];
+  /** The collections `resources/data.ts` declares, in file order. */
+  collections: DeclaredCollection[];
   /** By file, line and column. */
   problems: ResourceProblem[];
 }
 
+/** What the data files declare of the people: the resources `principalOf` takes, and what is wrong in their files. */
+export interface DeclaredPeople {
+  people: DeclaredResource[];
+  /**
+   * The problems in each file that declares (or tries to declare) a person, agent or group, and
+   * an id two of them share or one of the runtime's own agents (`RUNTIME_AGENTS`) takes. While
+   * there are any, nobody is admitted: a broken file never admits more than it says.
+   */
+  problems: ResourceProblem[];
+}
+
+/** A file that imports the runtime's constructors, `sanoma` (by any local name): the files `readPeople` reads. */
+const DECLARES_PEOPLE = /\{[^}]*\bsanoma\b[^}]*\}\s*from\s*["'](?:sanoma|@sanoma-ai\/workflows)\/resources["']/;
+/** The last read of the people under each root, by what its data files were then (`filesStamp`). */
+const peopleRead = new Map<string, { stamp: string; read: DeclaredPeople }>();
+
+/** Each data file under `root` with its size and modification time: unchanged while the files are. */
+const filesStamp = (root: string) =>
+  dataFilesUnder(join(root, "resources"))
+    .map((path) => {
+      // Gone since it was listed (an editor's save by rename): stamped as such, and read next time.
+      const stat = statSync(path, { bigint: true, throwIfNoEntry: false });
+      return `${path} ${stat?.size} ${stat?.mtimeNs}`;
+    })
+    .join("\n");
+
 /**
- * The resources the config's data files declare, read without importing or running them; throws
- * one error listing every problem, each at `file:line:column`, for a test or CI to fail on.
- * `describeConfig` lists the same, with the problems beside them instead.
+ * The people, agents and groups the data files under `root` declare (`sanoma.person`, `.agent`,
+ * `.group`), read without running them, as `principalOf` takes them, with what is wrong in their
+ * files; none without a root. Read again only when a data file changed (by its size and time),
+ * so a new colleague is admitted once their file is saved, and a request costs a `stat` per file.
  */
-export function readResources(config: SanomaConfig): DeclaredResource[] {
-  const { resources, problems } = readDataFiles(rootOf(config), config.connectors);
+export function readPeople(root: string | undefined): DeclaredPeople {
+  if (root === undefined) return { people: [], problems: [] };
+  const stamp = filesStamp(root);
+  const cached = peopleRead.get(root);
+  if (cached?.stamp === stamp) return cached.read;
+  const read = readDataFiles(root, [peopleConnector], undefined, (source) => DECLARES_PEOPLE.test(source));
+  const people = read.resources;
+  // The people are never bound, so the lockfile's problems are not theirs.
+  const own = read.problems.filter((p) => p.file !== LOCKFILE);
+  const ids = new Map<string, DeclaredResource>();
+  for (const r of people) {
+    if (r.type === "group") {
+      if (r.name === AGENTS) {
+        own.push({
+          file: r.file,
+          message: `${r.id} is named "${AGENTS}", the group every agent is in: give it another name`,
+        });
+      }
+      continue;
+    }
+    const id = r.name;
+    const other = ids.get(id);
+    if (other || RUNTIME_AGENTS.includes(id)) {
+      own.push({
+        file: r.file,
+        message: other
+          ? `${r.id} has the id "${id}", which ${other.id} has: give each person and agent their own`
+          : `${r.id} has the id "${id}", one of the runtime's own agents': give it another`,
+      });
+    }
+    ids.set(id, r);
+  }
+  const declared = { people, problems: own };
+  peopleRead.set(root, { stamp, read: declared });
+  return declared;
+}
+
+/**
+ * Who `asking` is admitted as, by the people the data files declare (`readPeople`): the declared
+ * principal (`principalOf`) of the id it names, a person's or an agent's; for a sign-in
+ * (`signIn`), of the person it matches (`personOf`: email, GitHub login, then id), never an agent.
+ * While no person is declared, whoever names an id is taken as given. Throws `NotAdmittedError`
+ * for anyone else, and for everyone while the people's files have problems.
+ */
+export function admit(
+  asking: { id?: string; email?: string; github?: string; groups?: string[]; onBehalfOf?: string },
+  { people, problems }: { people: readonly PeopleResource[]; problems: readonly ResourceProblem[] },
+  signIn = false,
+): Principal {
+  const who = asking.github ?? asking.id ?? asking.email ?? "This sign-in";
   if (problems.length) {
-    const lines = problems.map((p) => `  ${problemLine(p)}`);
-    throw new Error(`The resources' data files have problems:\n${lines.join("\n")}`);
+    // The runtime's own agents are declared by no file, so a broken one does not stop them (`check`'s scenarios).
+    if (!signIn && asking.id !== undefined && RUNTIME_AGENTS.includes(asking.id)) {
+      return principalOf(asking.id, people)!;
+    }
+    throw new NotAdmittedError(who, problems.map(problemLine));
+  }
+  if (!declaresPeople(people)) {
+    const given = Principal.safeParse(asking).data;
+    if (given) return given;
+  } else {
+    const id = signIn ? personOf(asking, people) : asking.id;
+    const admitted = id === undefined ? undefined : principalOf(id, people);
+    if (admitted) return admitted;
   }
-  return resources;
+  throw new NotAdmittedError(who);
 }
 
 interface FileEntry {
@@ -93,14 +215,21 @@ interface FileEntry {
  * type the connector does not declare, a value the type refuses (a reference where its type
  * takes none among them), a reference cycle, and two resources of one type with one identity.
  *
+ * The collections `resources/data.ts` declares are listed as they are read (`collections`),
+ * never matched to a connector, a resource type or the lockfile: the runtime imports that file.
+ *
  * Each declaration is joined to its binding in the lockfile (`readLockfile`) by its key,
  * `<file>#<export>`; a binding no export declares is an orphan. Problems: the lockfile's, a
  * binding of another type than its declaration's, and two declarations bound to one object.
+ *
+ * `partial` reads part of the files: only those whose source it passes, and in them, an import of
+ * a connector not in `connectors`, or of a file left out, is left unread rather than reported.
  */
 export function readDataFiles(
   root: string | undefined,
   connectors: readonly Connector<any, any>[],
   types: ReadonlyMap<string, Resource> = resourceTypesOf(connectors),
+  partial?: (source: string) => boolean,
 ): DataFiles {
   const problems: ResourceProblem[] = [];
   if (root === undefined) {
@@ -108,15 +237,20 @@ export function readDataFiles(
       message:
         "The config has no root, so its data files cannot be found: make it with defineConfig, which records its file, or set its `root`",
     });
-    return { resources: [], bindings: {}, orphans: [], problems };
+    return { resources: [], bindings: {}, orphans: [], collections: [], problems };
   }
   const lock = readLockfile(root);
   problems.push(...lock.problems);
 
   const files = new Map<string, FileEntry>();
+  const left = new Set<string>();
   for (const path of dataFilesUnder(join(root, "resources"))) {
     const rel = relative(root, path).split(sep).join("/");
     const source = readFileSync(path, "utf8");
+    if (partial && !partial(source)) {
+      left.add(path);
+      continue;
+    }
     const { program, problems: syntax, at } = parsed(source, path);
     const data = readDataFile(program, path, join(root, "resources"));
     const problem = (offset: number, message: string) => problems.push({ file: rel, ...at(offset), message });
@@ -131,6 +265,8 @@ export function readDataFiles(
     const { id, info } = connector[VENDOR];
     if (info?.package) entries.set(`${info.package}/resources`, id);
   }
+  // The runtime's own (`peopleConnector`, package `sanoma`) is imported from either name of its entry.
+  if (entries.get("sanoma/resources") === "sanoma") for (const entry of SECRET_ENTRIES) entries.set(entry, "sanoma");
 
   // What each file's names stand for, and every resource read by its id.
   const vendors = new Map<FileEntry, Map<string, string>>();
@@ -142,6 +278,7 @@ export function readDataFiles(
     for (const imp of file.data.imports) {
       if (imp.kind === "constructors") {
         const vendor = entries.get(imp.source);
+        if (vendor === undefined && partial) continue;
         if (vendor === undefined) {
           file.problem(
             imp.start,
@@ -157,7 +294,9 @@ export function readDataFiles(
         }
         continue;
       }
-      const other = files.get(resolve(dirname(path), imp.source));
+      const target = resolve(dirname(path), imp.source);
+      const other = files.get(target);
+      if (!other && left.has(target)) continue;
       if (!other) {
         file.problem(imp.start, `"${imp.source}" is not a data file under resources/`);
       } else if (!other.data.declared.includes(imp.imported)) {
@@ -293,19 +432,21 @@ export function readDataFiles(
       refs: result.refs,
     });
   }
+  const collections = [...files.values()].flatMap(({ rel, data }) =>
+    data.collections.map((c) => ({
+      id: `${rel}#${c.export}`,
+      file: rel,
+      name: c.name,
+      span: [c.start, c.end] as Span,
+    })),
+  );
   problems.sort(
     (a, b) =>
       (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0),
   );
-  return { resources, bindings: lock.bindings, orphans, problems };
+  return { resources, bindings: lock.bindings, orphans, collections, problems };
 }
 
-/** The data files under `dir`, sorted: regular `.ts` files, less tests, declarations and `node_modules`; none when `dir` is not a directory. */
-function dataFilesUnder(dir: string): string[] {
-  if (!statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return [];
-  return readdirSync(dir, { recursive: true, withFileTypes: true })
-    .filter((d) => d.isFile() && d.name.endsWith(".ts") && !d.name.endsWith(".test.ts") && !d.name.endsWith(".d.ts"))
-    .map((d) => join(d.parentPath, d.name))
-    .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
-    .toSorted();
-}
+/** The data files under `dir`, sorted: regular `.ts` files, less tests, declarations and `node_modules`. */
+const dataFilesUnder = (dir: string): string[] =>
+  filesUnder(dir, (name) => name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts"));

package/src/run.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { ApprovalState, Principal, WorkflowDefinition } from "./define.ts";
+import type { Collection } from "./collection.ts";
+import type { ApprovalState, Approver, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
 import type { LedgerStore } from "./ledger.ts";
 import type { DriverFn, Op } from "./op.ts";
@@ -16,6 +17,18 @@ export interface RunArgs {
   startedBy: Principal;
   /** The scenario a sandbox run is seeded from; the run calls the fakes instead of the drivers. */
   sandbox?: string;
+  /**
+   * The policy's hold on the start (`workflow:<name>`), as `SanomaClient.start` was answered: the
+   * run waits for this approval before its body runs.
+   */
+  hold?: StartHold;
+}
+
+/** A start the policy held: whom it asks, the approval's title, and the rules that held it. */
+export interface StartHold {
+  approver: Approver;
+  title: string;
+  reasons?: string[];
 }
 
 /**
@@ -37,9 +50,13 @@ export interface WorkerState {
   /** The worker's `source`, when it was given one. */
   source?: Source;
   types: ReadonlyMap<string, Resource>;
+  /** The collections, by name, which scenarios' steps may name (`data.<name>`). */
+  collections: ReadonlyMap<string, Collection>;
   steps: readonly Steps[];
   /** Its `version`, when it has one, is recorded with each of its decisions. */
   policy: Policy;
+  /** The config's directory, whose data files declare the people an approval's decider is checked against (`readPeople`). */
+  root?: string;
   ledger: LedgerStore;
   /** The stored secrets, for a live run's drivers (`CallContext.secrets`). */
   secrets: Secrets;