@sanoma-ai/workflows 0.9.1 → 0.10.1

package/src/op.ts

@@ -1,3 +1,6 @@
+import type { Principal } from "./define.ts";
+import type { Authentication, CallAuthentication } from "./authentication.ts";
+import type { ConnectionSnapshot } from "./connection.ts";
 import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
@@ -38,6 +41,8 @@ export interface OpSpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z
    * (a resource type's `handle`): the ledger records each as `"<name>"`, never its value.
    */
   opaque?: readonly string[];
+  /** Logical destinations this operation may create with Secrets.ensure, derived from its authorized input. */
+  createsSecrets?: (input: any) => readonly string[];
 }
 
 /** One vendor operation, such as `ghost.post.publish`. Declares the contract only; drivers implement it. */
@@ -56,6 +61,7 @@ export interface Op<V extends string = string, R extends string = string, N exte
   readonly phrases?: { readonly given?: string; readonly expect?: string };
   /** From the spec: fields the ledger records by name only. */
   readonly opaque?: readonly string[];
+  readonly createsSecrets?: (input: any) => readonly string[];
   readonly input: z.ZodType<any, I>;
   readonly output: z.ZodType<O>;
 }
@@ -108,7 +114,7 @@ export type Connector<V extends string, S extends Specs> = {
  * 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 const CONNECTOR_FORMAT = 1;
+export const CONNECTOR_FORMAT = 3;
 
 /**
  * A connector's vendor: its id, who it is (`defineConnector`'s third argument, for a UI), its
@@ -209,6 +215,7 @@ export function defineConnector<const V extends string, const S extends Specs>(
         target: spec.target,
         phrases: spec.phrases,
         ...(spec.opaque?.length ? { opaque: spec.opaque } : {}),
+        ...(spec.createsSecrets && { createsSecrets: spec.createsSecrets }),
         input: spec.input,
         output: spec.output,
       } satisfies Op);
@@ -236,6 +243,12 @@ export function defineConnector<const V extends string, const S extends Specs>(
  * not repeat the side effect.
  */
 export interface CallContext {
+  /** Authenticated initiating principal; never supplied by operation input. */
+  principal?: Principal;
+  /** Authorized account metadata. Credential material stays inside the driver boundary. */
+  connection?: ConnectionSnapshot;
+  /** Resolved after policy, for this call alone. Never return it from a driver. */
+  authentication?: CallAuthentication;
   idempotencyKey: string;
   runId: string;
   opId: string;
@@ -295,13 +308,15 @@ export function retryableStatus(status: number): boolean {
 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.
+ * Implements a vendor's operations, keyed `"resource.name"`. Named authentication is supplied
+ * in the call context. `env` describes a driver that has not added named-account support.
  */
 export interface Driver {
   readonly vendor: string;
   readonly ops: Readonly<Record<string, DriverFn>>;
   readonly env?: DriverEnv;
+  /** Methods this driver consumes from CallContext.authentication. Others fail closed. */
+  readonly authentication?: readonly string[];
 }
 
 /**
@@ -313,7 +328,9 @@ export interface Driver {
  * no repository a change is reviewed on.
  */
 export interface ConnectorSetup {
-  /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
+  /** Auth methods available to named connections; login identity is separate. */
+  authentication?: Readonly<Record<string, Authentication>>;
+  /** Makes the live driver once per resolved config; credentials belong to each invocation. */
   driver?: () => Driver;
   /** Makes a fake of the vendor (`defineFake`): once per sandbox run, its own. */
   fake?: () => Fake<any, any>;
@@ -457,8 +474,8 @@ export type OpIdOf<V extends string, S extends Specs> = {
  */
 export function defineDriver<V extends string, S extends Specs>(
   connector: Connector<V, S>,
-  impl: DriverImpl<S>,
-  options: { env?: DriverEnv } = {},
+  impl: DriverImpl<S> | ((call: CallContext) => DriverImpl<S>),
+  options: { env?: DriverEnv; authentication?: readonly string[] } = {},
 ): Driver {
   const declared = new Map<string, Op>();
   for (const resource of Object.values(connector as Record<string, Record<string, unknown>>)) {
@@ -466,6 +483,18 @@ export function defineDriver<V extends string, S extends Specs>(
   }
   const vendor = connector[VENDOR].id;
   const ops: Record<string, DriverFn> = {};
+  if (typeof impl === "function") {
+    // Build clients only once the runtime has authorized and authenticated this invocation.
+    for (const key of declared.keys()) {
+      ops[key] = async (input, call) => defineDriver(connector, impl(call), options).ops[key]!(input, call);
+    }
+    return Object.freeze({
+      vendor,
+      ops: Object.freeze(ops),
+      ...(options.env && { env: options.env }),
+      ...(options.authentication && { authentication: Object.freeze([...options.authentication]) }),
+    });
+  }
   const extra: string[] = [];
   for (const [resource, fns] of Object.entries(impl as Record<string, Record<string, unknown>>)) {
     for (const [name, fn] of Object.entries(fns ?? {})) {
@@ -480,5 +509,10 @@ export function defineDriver<V extends string, S extends Specs>(
     ...(extra.length ? [`it implements ${extra.join(", ")}, which the connector does not declare`] : []),
   ];
   if (problems.length) throw new Error(`defineDriver("${vendor}"): ${problems.join("; ")}`);
-  return Object.freeze({ vendor, ops: Object.freeze(ops), ...(options.env && { env: options.env }) });
+  return Object.freeze({
+    vendor,
+    ops: Object.freeze(ops),
+    ...(options.env && { env: options.env }),
+    ...(options.authentication && { authentication: Object.freeze([...options.authentication]) }),
+  });
 }

package/src/outline.ts

@@ -44,7 +44,7 @@ export type OutlineNode = { path: string; span: Span } &
    */
   /** `name`: the one the call gives (`ctx.x.y.z(input, { name: "…" })`), else the id when no segment is computed. */
   (
-    | { kind: "op"; id: string; ops?: string[]; name?: string }
+    | { kind: "op"; id: string; ops?: string[]; name?: string; connection?: { id: string } | { dynamic: true } }
     /**
      * `ctx.approval(...)`, with its title, and the title as its `name`, when the first argument is
      * a string literal or a top-level `const` holding one.
@@ -391,12 +391,25 @@ export function outlineBody(
    * A step's name as the call gives it, in `{ name: "…" }` after the call's input: a string
    * literal or a top-level const, not an operation's id or `Sleep`, which unnamed calls are called.
    */
-  const nameIn = (options: Node | undefined): string | undefined => {
+  const nameIn = (options: Node | undefined, connection = false): string | undefined => {
     if (options === undefined) return undefined;
     const literal = unwrap(options);
-    const property =
-      literal?.type === "ObjectExpression" && literal.properties.length === 1 ? literal.properties[0] : undefined;
-    const key = property?.type === "Property" && !property.computed ? (property.key.name ?? property.key.value) : "";
+    if (
+      literal?.type !== "ObjectExpression" ||
+      literal.properties.some(
+        (p: Node) =>
+          p.type !== "Property" ||
+          p.computed ||
+          !(connection ? ["name", "connection"] : ["name"]).includes(p.key.name ?? p.key.value),
+      )
+    ) {
+      problem(options, NAME);
+      return undefined;
+    }
+    const property = literal.properties.find((p: Node) => (p.key.name ?? p.key.value) === "name");
+    if (!property && literal.properties.some((p: Node) => (p.key.name ?? p.key.value) === "connection"))
+      return undefined;
+    const key = property?.key.name ?? property?.key.value;
     const name = key === "name" ? literalOf(property.value, consts) : undefined;
     if (name === undefined || !/\S/.test(name)) problem(options, NAME);
     else if (name === DEFAULT_SLEEP_NAME || OP_ID.test(name)) problem(options, DEFAULT_LIKE(name));
@@ -404,6 +417,31 @@ export function outlineBody(
     return undefined;
   };
 
+  // Dependency information only. Execution still resolves and authorizes the actual reference.
+  // An imported/computed reference stays unknown rather than being guessed from its variable name.
+  const connectionIn = (options: Node | undefined): { id: string } | { dynamic: true } | undefined => {
+    if (!options) return undefined;
+    const object = options && unwrap(options);
+    if (object?.type !== "ObjectExpression") return { dynamic: true };
+    if (object.properties.some((p: Node) => p.type !== "Property" || p.computed)) return { dynamic: true };
+    const property =
+      object?.type === "ObjectExpression" &&
+      object.properties.findLast(
+        (p: Node) => p.type === "Property" && !p.computed && (p.key.name ?? p.key.value) === "connection",
+      );
+    if (!property) return undefined;
+    const ref = unwrap(property.value);
+    if (ref?.type !== "ObjectExpression") return { dynamic: true };
+    if (ref.properties.some((p: Node) => p.type !== "Property" || p.computed)) return { dynamic: true };
+    const key =
+      ref?.type === "ObjectExpression" &&
+      ref.properties.findLast(
+        (p: Node) => p.type === "Property" && !p.computed && (p.key.name ?? p.key.value) === "$connection",
+      );
+    const id = key && literalOf(key.value, consts);
+    return typeof id === "string" ? { id } : { dynamic: true };
+  };
+
   // The arguments are evaluated before the call is made, so their calls come first.
   const call = (node: Node, at: Where): OutlineNode[] => {
     const args: Node[] = node.arguments;
@@ -428,10 +466,18 @@ export function outlineBody(
         default:
           if (isOpPath(members)) {
             // A computed id's own name is the operation it calls, known only in a run.
-            const name = nameIn(args[1]) ?? (id.includes("*") ? undefined : id);
+            const name = nameIn(args[1], true) ?? (id.includes("*") ? undefined : id);
+            const connection = connectionIn(args[1]);
             return [
               ...walk(args, at),
-              { kind: "op", path, id, span: span(node), ...(name === undefined ? {} : { name }) },
+              {
+                kind: "op",
+                path,
+                id,
+                span: span(node),
+                ...(name === undefined ? {} : { name }),
+                ...(connection && { connection }),
+              },
             ];
           }
           return READS.has(id) ? walk(args, at) : [...walk(args, at), ...problem(node, CTX_CALL(id))];

package/src/paths.ts

@@ -1,11 +1,26 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { APP_NAME } from "./shared.ts";
+import { APP_NAME, APPS_DIR, appOfPath } from "./shared.ts";
 
 // Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
 // the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
 // the oxlint plugin loads it.
 
+/**
+ * Where a data file imports `secret` from, and `sanoma`, the runtime's own resource constructors
+ * (its people: `sanoma.person`, `.agent`, `.group`): what the loader serves for them.
+ */
+export const SECRET_ENTRIES: ReadonlySet<string> = new Set(["sanoma/resources", "@sanoma-ai/workflows/resources"]);
+/** Where a site imports `api`, `RunForm` and `defineSite` from: `sanoma/site`, which re-exports the app's. The loader serves `defineSite`. */
+export const SITE_ENTRIES: ReadonlySet<string> = new Set(["sanoma/site", "@sanoma-ai/app/site"]);
+/** Where `resources/data.ts` imports `collection` from: what the loader serves for it. */
+export const DATA_ENTRIES: ReadonlySet<string> = new Set(["sanoma/data", "@sanoma-ai/workflows/data"]);
+/**
+ * The one data file that holds collections, relative to `resources/`. Workflows and the runtime
+ * import it, so it holds collections only.
+ */
+export const COLLECTIONS_FILE = "data.ts";
+
 /** A relative import specifier: `./x.ts`, `../y.ts`. */
 export const RELATIVE = /^\.\.?\//;
 
@@ -34,6 +49,9 @@ export function inside(dir: string, path: string): boolean {
   return rel === "" || (rel.split(sep)[0] !== ".." && !isAbsolute(rel));
 }
 
+/** `path`, under `root`, relative to it with `/`: `resources/github.ts`. */
+export const relPath = (root: string, path: string): string => relative(root, path).split(sep).join("/");
+
 /** True when `path` is a directory. */
 export const isDirectory = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
 
@@ -47,8 +65,7 @@ export function filesUnder(dir: string, keep: (name: string) => boolean): string
     .toSorted();
 }
 
-/** Where a company's apps are, under its root: `apps/<app>/`. */
-export const APPS_DIR = "apps";
+export { APPS_DIR, appOfPath };
 
 /** Each directory's company root (the nearest one with a `sanoma.config.ts`, short of a `node_modules`), once found. */
 const roots = new Map<string, string>();
@@ -77,9 +94,7 @@ export function appOfFile(file: string | undefined): string | undefined {
     // Found roots only: a directory that is no company's yet may become one (`sanoma` in an empty folder).
     if (root !== null) roots.set(dir, root);
   }
-  if (root === null) return undefined;
-  const [top, app, ...rest] = relative(root, file).split(sep);
-  return top === APPS_DIR && app !== undefined && rest.length && APP_NAME.test(app) ? app : undefined;
+  return root === null ? undefined : appOfPath(relPath(root, file));
 }
 
 /** The apps' folders under `root` whose names are an `APP_NAME`, sorted: `apps/<app>/`, absolute. */

package/src/plugin.ts

@@ -1,9 +1,6 @@
-import { readDataFile } from "./datafile.ts";
-
-// An oxlint JS plugin with two rules, on the trees oxlint has already parsed, which the package's
-// `oxlint.json` turns on: `sanoma/data-file` for `resources/**`, the data-file subset
-// `readResources` reads, the same check as `lintResources`; and `sanoma/date` for `workflows/**`,
-// `Date` reading the clock. Typed here by the little they use, so the package needs no oxlint types.
+// An oxlint JS plugin with one rule, on the trees oxlint has already parsed, which the package's
+// `oxlint.json` turns on for `workflows/**`: `sanoma/date`, `Date` reading the clock. Typed here by
+// the little it uses, so the package needs no oxlint types.
 
 interface Context {
   filename: string;
@@ -65,24 +62,6 @@ function readsNoClock(node: Node): boolean {
 const plugin = {
   meta: { name: "sanoma" },
   rules: {
-    "data-file": {
-      meta: {
-        type: "problem",
-        docs: {
-          description:
-            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`; resources/data.ts holds only collections, `collection({ … })` from sanoma/data",
-        },
-      },
-      create(context: Context) {
-        return {
-          Program(program: unknown) {
-            for (const { start, end, message } of readDataFile(program, context.filename).problems) {
-              context.report({ message, node: { range: [start, end] } });
-            }
-          },
-        };
-      },
-    },
     // `Date` reads the clock in `Date.now()`, `new Date()` and `Date()`, which a replay would read
     // again; a workflow reads it with `ctx.now()`, recorded. Every other use of `Date` is pure:
     // `new Date(value)` (of `await ctx.now()`, or of a date the workflow has), `Date.parse`, `Date.UTC`.

package/src/policy.ts

@@ -1,3 +1,4 @@
+import type { ConnectionSnapshot } from "./connection.ts";
 import { type ApprovalState, type Approver, type Principal, sameApprover } from "./define.ts";
 import type { Effect, Op } from "./op.ts";
 import { CALL_WORKFLOW, isVisitor } from "./shared.ts";
@@ -16,6 +17,7 @@ export const policyOpOf = ({ id, vendor, resource, name, effect }: Op): PolicyOp
 
 /** What a policy sees for each operation a run calls: plain data. */
 export interface PolicyCall {
+  connection?: ConnectionSnapshot;
   op: PolicyOp;
   /** The same as `op.effect`. */
   effect: Effect;

package/src/resource.ts

@@ -1,3 +1,4 @@
+import type { ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { checkDatabase, type DatabaseSpec } from "./database.ts";
 import { isRunControlError } from "./errors.ts";
@@ -173,7 +174,7 @@ export async function callAfterCreate(
  */
 export const DECLARED: unique symbol = Symbol.for("sanoma.declared");
 
-/** A resource a data file declares: `github.repository({ name: "sanoma" })`. */
+/** A resource a data file declares: `github.repository({ owner: "acme", name: "sanoma" })`. */
 export interface Declared<Id extends string = string, T = State> {
   readonly [DECLARED]: Id;
   readonly vendor: string;
@@ -185,6 +186,7 @@ export interface Declared<Id extends string = string, T = State> {
    * checked, and what a drift check compares.
    */
   readonly desired: T;
+  readonly connection?: ConnectionRef;
   /**
    * Where it names another resource: the field's dotted path (a list item's with its index,
    * `teams.0`) to that resource's `<vendor>.<type>:<name>`.
@@ -331,7 +333,10 @@ export interface Resource<
       >
     >,
     Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate">> {
-  (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
+  (
+    desired: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef<Id extends `${infer V}.${string}` ? V : string> },
+  ): 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. */
   readonly ops: ResourceOps<S, W>;
   /** True when apply may change its objects: it has the change operations. */
@@ -349,7 +354,9 @@ export const isObject = (v: unknown): v is State => typeof v === "object" && v !
 /** `path.name`, or `name` at the top: a field's dotted path. */
 export const joinPath = (path: string, name: string) => (path ? `${path}.${name}` : name);
 
-const isDeclared = (v: unknown): v is Declared => isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
+/** A declared resource: what a constructor returns, made by any copy of this package. */
+export const isDeclared = (v: unknown): v is Declared =>
+  isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
 
 /** One order for a list compared as a multiset: by each item's JSON. */
 const canonical = (items: unknown[]) =>
@@ -577,8 +584,8 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  *
  * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
  *
- * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
- * is a `Declared`, `{ vendor, type, name: "sanoma", desired, refs: {} }`. It refuses fields the
+ * Calling the result declares one resource, for a data file: `repository({ owner: "acme", name: "sanoma" })`
+ * is a `Declared`, `{ vendor, type, name: "acme/sanoma", desired, refs: {} }`. It refuses fields the
  * schema does not have, fields the vendor owns (unless the identity names them), values the
  * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
  * another declared resource of that type (`repository_id: site`): `desired` holds, and the
@@ -663,7 +670,17 @@ export function defineResource<
   const owned = new Set(fields.vendorOwned.filter((path) => !named.has(path)));
   const references: References = fields.references ?? {};
   const writeOnly = new Set(fields.writeOnly);
-  const declare = (given: Declaring<z.input<S>, R>): Declared<`${V}.${T}`, z.input<S>> => {
+  const declare = (
+    given: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef },
+  ): Declared<`${V}.${T}`, z.input<S>> => {
+    const connection = options?.connection;
+    if (
+      connection &&
+      (connection.vendor !== vendor || !new RegExp(`^${vendor}/[a-z][a-z0-9-]{0,63}$`).test(connection.$connection))
+    ) {
+      throw new Error(`${what}: select a declared connection of this connector`);
+    }
     const refs: Record<string, string> = {};
     // Where a secret is given, with list items' indexes: the schema does not judge its marker.
     const secrets = new Set<string>();
@@ -723,6 +740,7 @@ export function defineResource<
       ...(name !== undefined && { name }),
       desired,
       refs: Object.freeze(refs),
+      ...(connection && { connection: Object.freeze({ ...connection }) }),
     });
   };
   const resource = Object.assign(declare, {