@sanoma-ai/workflows 0.6.0 → 0.7.1

package/src/sandbox.ts

@@ -4,7 +4,7 @@ import { opIdsOf } from "./define.ts";
 import { SanomaError } from "./errors.ts";
 import type { Fake, ResourceFake } from "./fake.ts";
 import { entry, type LedgerRecord, write } from "./ledger.ts";
-import type { DriverFn } from "./op.ts";
+import type { CallContext, DriverFn, Op } from "./op.ts";
 import type { Run } from "./run.ts";
 import { memorySecrets } from "./secret.ts";
 import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
@@ -58,7 +58,7 @@ export function seedResource(
   scenario: string,
   copy: ResourceFake,
   given: Extract<Given, { resource: string }>,
-): Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"][number] {
+): Seeds[number] {
   const { resource, type, name } = given;
   try {
     if ("gone" in given) {
@@ -77,16 +77,81 @@ export function seedResource(
   }
 }
 
+/** What a scenario's `Given` steps seeded, as its `scenario.seeded` record has it. */
+export type Seeds = Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"];
+
+/**
+ * Where a scenario's `Given` steps go (`applyGivens`): a sandbox run's own fakes (`run`), or the
+ * instance a demo runs (`instance`), its collections in the config's database and every vendor
+ * on its one fake, which every run shares, so a fault, injected into a call some other run would
+ * make, is refused there.
+ */
+export interface GivenTarget {
+  kind: "run" | "instance";
+  /** What a `Given` operation is called through, by operation id. */
+  drivers: ReadonlyMap<string, DriverFn>;
+  /** The fakes, by vendor id: what a `Given` resource is put in, and a `run`'s faults injected into. */
+  fakes: ReadonlyMap<string, Fake<unknown>>;
+  /** The operations by id, for a fault's vendor. */
+  ops: ReadonlyMap<string, Op>;
+  /** The context of the call the `i`th `Given` makes. */
+  call(i: number, op: string): CallContext;
+}
+
+/**
+ * Applies the scenario's `Given` steps to the target: calls each operation through its drivers,
+ * puts or removes each resource in its vendor's fake, then, for a `run`, injects the faults.
+ * Checks first that every operation it seeds has a driver there, that every resource's vendor has
+ * a fake holding resources, and, for an `instance`, that it injects no fault. Returns what it
+ * seeded, in order.
+ */
+export async function applyGivens(scenario: Pick<Scenario, "name" | "given">, target: GivenTarget): Promise<Seeds> {
+  const { name, given } = scenario;
+  const fault = given.find((g) => "fault" in g);
+  if (fault && target.kind === "instance") {
+    throw new SanomaError(
+      "invalid_input",
+      `Scenario "${name}" injects a fault ("${fault.step}"), but its Givens go to the instance, whose fakes every run shares`,
+      { scenario: name, step: fault.step },
+    );
+  }
+  const missing = [...new Set(given.flatMap((g) => ("op" in g && !target.drivers.has(g.op) ? [g.op] : [])))];
+  if (missing.length) {
+    throw new SanomaError(
+      "invalid_input",
+      `Scenario "${name}" seeds ${missing.join(", ")}, but no fake its connectors attach implements ${missing.length > 1 ? "them" : "it"}`,
+      { scenario: name, missing },
+    );
+  }
+  const plain = missingResourceFake(scenario, target.fakes);
+  if (plain) throw plain;
+  const seeded: Seeds = [];
+  for (const [i, g] of given.entries()) {
+    if ("fault" in g) continue;
+    if ("op" in g) {
+      const output = await target.drivers.get(g.op)!(g.input, target.call(i, g.op));
+      seeded.push({ op: g.op, input: g.input, output });
+      continue;
+    }
+    // Checked above: the vendor's fake holds resources.
+    seeded.push(seedResource(name, target.fakes.get(g.vendor) as Fake<unknown> & ResourceFake, g));
+  }
+  for (const g of given) {
+    if ("fault" in g) target.fakes.get(target.ops.get(g.op)!.vendor)![g.fault](g.op);
+  }
+  return seeded;
+}
+
 /**
  * Seeds a sandbox run of the scenario `name`, from the worker, in one step: reads the scenario,
- * checks that it runs this workflow, makes the run's own fakes (each vendor's maker, called once
- * for the run), checks that every operation the workflow uses or the scenario seeds has one and
- * that every resource it seeds has a fake holding resources, calls each `Given` operation
- * through them, puts or removes each `Given` resource in them, injects the faults into them,
- * then puts their functions on the run. The run then calls those only, so sandbox runs share no
- * state when the makers make a new fake each. The step's checkpoint never stands in for them: a
- * run whose seeding is replayed from it has none, and fails, since a sandbox run does not
- * survive a worker restart.
+ * checks that it runs this workflow, picks the run's fakes, checks that every operation the
+ * workflow uses has one, then applies the scenario's `Given` steps to them
+ * (`applyGivens`) and puts their functions on the run. The run then calls those only. Its fakes
+ * are its own (each vendor's maker, called once for the run), so sandbox runs share no state when
+ * the makers make a new fake each; on an instance that runs on fakes (`instanceFakes`) they are
+ * the instance's, which its sandbox runs share, as its live drivers are. The step's checkpoint
+ * never stands in for a run's own: a run whose seeding is replayed from it has none, and fails,
+ * since a sandbox run does not survive a worker restart; on an instance's fakes it goes on with them.
  */
 export async function seedSandbox(run: Run, name: string): Promise<void> {
   const { state } = run;
@@ -103,19 +168,22 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
         throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
       }
       if (scenario.workflow !== run.workflow) {
-        throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
+        const runs = scenario.workflow === undefined ? "is a world, which runs nothing" : `runs ${scenario.workflow}`;
+        throw new SanomaError("invalid_input", `Scenario "${name}" ${runs}, not ${run.workflow}`, {
           scenario: name,
-          workflow: scenario.workflow,
+          ...(scenario.workflow !== undefined && { workflow: scenario.workflow }),
         });
       }
-      const fakes = new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
-      const drivers = indexDrivers(
-        [...fakes.values()].map((f) => f.driver),
-        state.ops,
-      );
-      const uses = opIdsOf(state.workflows.get(run.workflow)!);
-      const seeding = scenario.given.flatMap((g) => ("op" in g ? [g.op] : []));
-      const missing = [...new Set([...uses, ...seeding])].filter((id) => !drivers.has(id));
+      const instance = state.instanceFakes;
+      const fakes = instance ?? new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
+      const drivers = instance
+        ? state.drivers
+        : indexDrivers(
+            [...fakes.values()].map((f) => f.driver),
+            state.ops,
+          );
+      // What the scenario seeds is checked by `applyGivens`.
+      const missing = opIdsOf(state.workflows.get(run.workflow)!).filter((id) => !drivers.has(id));
       if (missing.length) {
         throw new SanomaError(
           "invalid_input",
@@ -123,28 +191,20 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
           { scenario: name, missing },
         );
       }
-      const plain = missingResourceFake(scenario, fakes);
-      if (plain) throw plain;
-      const seeded: Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"] = [];
-      for (const [i, given] of scenario.given.entries()) {
-        if ("fault" in given) continue;
-        if ("op" in given) {
-          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1, secrets };
-          const output = await drivers.get(given.op)!(given.input, call);
-          seeded.push({ op: given.op, input: given.input, output });
-          continue;
-        }
-        // Checked above: the vendor's fake holds resources.
-        seeded.push(seedResource(name, fakes.get(given.vendor) as Fake<unknown> & ResourceFake, given));
-      }
-      for (const given of scenario.given) {
-        if ("fault" in given) fakes.get(state.ops.get(given.op)!.vendor)![given.fault](given.op);
-      }
+      const seeded = await applyGivens(scenario, {
+        kind: instance ? "instance" : "run",
+        drivers,
+        fakes,
+        ops: state.ops,
+        call: (i, opId) => ({ idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId, attempt: 1, secrets }),
+      });
       copies = drivers;
       return { seeds: seeded };
     },
     { name: "sandbox:seed" },
   );
+  // Replayed on an instance that runs on fakes: they are the instance's, still there in this process.
+  if (!copies && state.instanceFakes) copies = state.drivers;
   if (!copies) {
     // Replayed from its checkpoint (after a worker restart, or in a fork), so the run has no fakes.
     // The records written before the restart hold the seqs from here on: the failure goes after them.

package/src/scenario.ts

@@ -135,7 +135,19 @@ export interface Scenario {
   file: string;
   /** Its line in the file: its keyword's, or for an outline's row, the row's. */
   line: number;
-  workflow: string;
+  /**
+   * The workflow its `When` runs. Absent for a scenario with no `When`, a *world*: its `Given`
+   * steps alone, which a demo applies to the instance (`applyGivens`) and nothing runs or checks.
+   */
+  workflow?: string;
+  /** Its tags, as written (`@slow`), the feature's and its own. */
+  tags: string[];
+  /**
+   * When it is tagged `@moment(<person>,<path>)` (no space: a Gherkin tag has none): a moment,
+   * which a demo starts as a sandbox run by `person`, a declared person, and leaves waiting, for
+   * a visitor signed in as them to land on at `path`.
+   */
+  moment?: Moment;
   /**
    * The scenario's own lines of its feature file, for display: from its keyword line to the end
    * of its last step (a step's doc string or table included, and an outline's examples), less
@@ -158,6 +170,12 @@ export interface Scenario {
   expect: Expectation[];
 }
 
+/** A moment's visitor and where they land: `@moment(<person>,<path>)`. */
+export interface Moment {
+  person: string;
+  path: string;
+}
+
 /** The result of one expectation against a run's ledger. */
 export interface Check {
   step: string;
@@ -380,6 +398,22 @@ function builtFor(scope: Scope): Built {
 /** A `Then` step of the generic steps: its expectation, checked against the run's records. */
 const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
+/**
+ * `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. The
+ * people are the root's data files' (`readPeople`, read again only once a file changed): while
+ * they declare no one, any id goes.
+ */
+function actorNamed(scope: Scope, who: string): string {
+  const declared = readPeople(scope.root);
+  try {
+    return admit({ id: who }, declared).id;
+  } catch (err) {
+    if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
+    const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
+    throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
+  }
+}
+
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
   const { types, collections } = scope;
@@ -403,20 +437,10 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
   ];
   const opOf = (id: unknown) => scope.ops.get(id as string)!;
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
-  // The people as the root's data files declare them when a step names one (`readPeople`, read
-  // again only once a file changed): while they declare no one, any id and any group go.
-  /** `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. */
-  const actorNamed = (who: string) => {
-    const declared = readPeople(scope.root);
-    try {
-      return admit({ id: who }, declared).id;
-    } catch (err) {
-      if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
-      const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
-      throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
-    }
-  };
-  /** `group`, a declared group or `agents`, while the people's files have no problems. */
+  /**
+   * `group`, a declared group or `agents`, while the people's files have no problems (`readPeople`,
+   * read again only once a file changed): while they declare no one, any group goes.
+   */
   const groupNamed = (group: string) => {
     const { people, problems } = readPeople(scope.root);
     if (problems.length) {
@@ -434,7 +458,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
     return { resource: id as string, vendor, type, name: name as string };
   };
   const rules: Rule[] = [
-    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
+    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(scope, who as string) },
     // A visitor of a public site, as a login would vouch for one; `anonymous` is a `{who}`.
     { kind: "actor", source: "a visitor is acting", read: () => visitorPrincipal("scenario", "visitor").id },
     {
@@ -881,7 +905,7 @@ function namesOf(report: Report): Map<string, string> {
 }
 
 /** What one scenario's steps said, as compiling it records them. */
-type Spec = Omit<Scenario, "workflow" | "approvals" | "file" | "line" | "text"> & { workflow?: string };
+type Spec = Omit<Scenario, "approvals" | "file" | "line" | "text" | "tags" | "moment">;
 
 /** The run's records, as a `Then` step reads them. */
 function viewOf(records: readonly LedgerRecord[]): RunView {
@@ -1177,6 +1201,28 @@ function stepError(built: Built, result: StepResult | undefined, step: PickleSte
   }
 }
 
+/**
+ * The moment its tags make a scenario (`@moment(<person>,<path>)`), the person admitted as a run's
+ * starter is, or undefined for none; throws, at `where`, for a malformed one or a second.
+ */
+function momentOf(scope: Scope, tags: readonly string[], where: string): Moment | undefined {
+  const tagged = tags.filter((t) => t === "@moment" || t.startsWith("@moment("));
+  if (tagged.length === 0) return undefined;
+  if (tagged.length > 1) throw new Error(`${where}: ${tagged.join(" and ")}: a moment has one person and one page`);
+  const [, person, path] = /^@moment\(([^,()]+),(\/[^()]*)\)$/.exec(tagged[0]!) ?? [];
+  if (person === undefined || path === undefined) {
+    throw new Error(
+      `${where}: ${tagged[0]} needs a person and a path, as in @moment(alex,/sites/portal/requests), with no space: a tag has none`,
+    );
+  }
+  try {
+    return { person: actorNamed(scope, person), path };
+  } catch (err) {
+    if (isBug(err)) throw err;
+    throw new Error(`${where}: ${tagged[0]}: ${errorMessage(err)}`, { cause: err });
+  }
+}
+
 /** The `.feature` files under `dir`, relative to it, with `/` between directories, in order. */
 function featureFiles(dir: string): string[] {
   return readdirSync(dir, { recursive: true, encoding: "utf8" })
@@ -1197,8 +1243,9 @@ const parseErrorOf = ({ uri, line, message }: Report["parseErrors"][number]) =>
 
 /**
  * Compiles the feature files `files` (relative to `dir`) into scenarios: Cucumber runs each,
- * and its steps record what they say. A file with an error has none of its scenarios: the
- * first error in it (a step that fails or matches no step or two, a scenario with no `When`,
+ * and its steps record what they say. A file none of whose scenarios has a `When` is of worlds.
+ * A file with an error has none of its scenarios: the
+ * first error in it (a step that fails or matches no step or two, a scenario with no `When` beside one with,
  * a name used twice, a file Gherkin cannot parse, no scenarios at all) is its error.
  */
 async function compile(scope: Scope, dir: string, files: string[]): Promise<LoadedScenarios> {
@@ -1234,6 +1281,8 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
       try {
         const list = pickles.get(file) ?? [];
         if (list.length === 0) throw new Error(`${file}: no scenarios; add one with "Scenario: <name>"`);
+        // A feature none of whose scenarios has a When is of worlds; elsewhere a missing When is a mistake.
+        const ofWorlds = list.every((p) => specs.get(p.id)!.workflow === undefined);
         for (const pickle of list) {
           const line = lineOf(report, pickle);
           const scenario = query.findLineageBy(pickle)!.scenario!;
@@ -1242,16 +1291,37 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
             const error = stepError(built, results.get(step.id), step, whereOf(report, file, step));
             if (error) throw new Error(error);
           }
-          const { workflow, ...spec } = specs.get(pickle.id)!;
+          const spec = specs.get(pickle.id)!;
+          const { workflow } = spec;
           const name = names.get(pickle.id)!;
           if (inFile.some((s) => s.name === name)) {
             throw new Error(`${where}: a second scenario named "${name}"; give each its own name`);
           }
-          if (workflow === undefined) {
+          const tags = pickle.tags.map((t) => t.name);
+          const moment = momentOf(scope, tags, where);
+          const common = { name, file, line, tags, text: textOf(scenario, report.texts.get(file) ?? "") };
+          if (workflow === undefined && !ofWorlds) {
             throw new Error(
-              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`,
+              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with" (a feature with no When in any scenario is of worlds)`,
             );
           }
+          if (workflow === undefined) {
+            // A world: its Givens alone, which nothing runs or checks.
+            const runs = moment
+              ? "is a moment, which starts a run"
+              : spec.expect[0]
+                ? `checks a run ("${spec.expect[0].step}")`
+                : spec.decisions[0]
+                  ? `decides an approval ("${spec.decisions[0].step}")`
+                  : undefined;
+            if (runs) {
+              throw new Error(
+                `${where}: scenario "${name}" has no When, so it is a world, Givens only, but it ${runs}: say which workflow runs, such as "When <workflow> runs with"`,
+              );
+            }
+            inFile.push({ ...spec, ...common, approvals: [] });
+            continue;
+          }
           // A step about a declared resource reads the report of the built-in it is about.
           for (const e of spec.expect) {
             const reads: string = "declared" in e ? ("status" in e ? DRIFT_WORKFLOW : APPLY_WORKFLOW) : workflow;
@@ -1263,11 +1333,9 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
           }
           inFile.push({
             ...spec,
-            name,
-            file,
-            line,
+            ...common,
             workflow,
-            text: textOf(scenario, report.texts.get(file) ?? ""),
+            ...(moment && { moment }),
             approvals: approvalsOf(scope.workflows.get(workflow)!),
           });
         }
@@ -1358,10 +1426,11 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
  */
 export async function check(scope: Scope, scenario: Scenario, records: readonly LedgerRecord[]): Promise<Check[]> {
   if (!scope.scenarios) throw new Error(`No scenarios directory to check scenario "${scenario.name}" from`);
+  const { file, line, name, workflow } = scenario;
+  if (workflow === undefined) throw new Error(`Scenario "${name}" is a world: it runs nothing to check`);
   const built = builtFor(scope);
-  const { file, line, name } = scenario;
   const verdicts = new Map<string, string | undefined>();
-  const report = await runFeatures(built.library, checkWorld(built, scenario.workflow, viewOf(records), verdicts), {
+  const report = await runFeatures(built.library, checkWorld(built, workflow, viewOf(records), verdicts), {
     cwd: fileURLToPath(scope.scenarios),
     files: [file],
     line,

package/src/scenarios.ts

@@ -6,11 +6,13 @@ import { type Check, check, drive, loadScenarios, type Scenario, type Scope } fr
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
 
+export { type DemoState, demoState, reseed } from "./demo.ts";
+
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test
  * framework. Server-side only, like `./scenario`: it loads Cucumber and starts a worker.
  * `sanoma check` runs every scenario through `runScenarios`; `@sanoma-ai/testing/scenarios` wraps
- * `runScenario` in a vitest test per scenario.
+ * `runScenario` in a vitest test per scenario. A demo seeds its instance with `reseed`.
  */
 
 export interface RunScenarioOptions {
@@ -30,12 +32,15 @@ export interface RunScenarioOptions {
 /**
  * Runs a scenario as a sandbox run: starts its workflow with its input, as whoever it says is
  * acting, decides its approvals as it says, and checks the run's ledger against it (`check`:
- * Cucumber runs its `Then` steps).
+ * Cucumber runs its `Then` steps). Refuses a world, which runs nothing.
  */
 export async function runScenario(
   scenario: Scenario,
   { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
+  if (scenario.workflow === undefined) {
+    throw new Error(`Scenario "${scenario.name}" is a world: it seeds a demo's instance, and runs nothing`);
+  }
   const runId = await client.start(scenario.workflow, scenario.input, {
     startedBy: scenario.startedBy ?? startedBy,
     sandbox: scenario.name,
@@ -64,6 +69,13 @@ export interface RunScenariosOptions {
   log?: (line: string) => void;
 }
 
+/**
+ * True for a scenario that is a test: one that runs a workflow (not a world), and not a moment
+ * that decides nothing, which a demo leaves waiting at its first approval.
+ */
+export const isTest = (scenario: Scenario): scenario is Scenario & { workflow: string } =>
+  scenario.workflow !== undefined && !(scenario.moment && scenario.decisions.length === 0);
+
 /**
  * Runs every scenario in `scenarios/` in the config's root, one after another, as sandbox runs
  * on a worker it starts on `databaseUrl` with an in-memory ledger (the config's `ledger` is not
@@ -72,6 +84,7 @@ export interface RunScenariosOptions {
  * could not be read, with why. A scenario whose run cannot be driven to its end (an approval
  * with no decision, a run still going after `timeoutMs`) fails with that error at its `When`
  * step. A config whose root has no `scenarios/`, or none in it, passes nothing and fails nothing.
+ * Worlds and moments that decide nothing are no tests (`isTest`): they are left out, each logged as skipped.
  */
 export async function runScenarios(
   config: SanomaConfig,
@@ -79,7 +92,9 @@ export async function runScenarios(
 ): Promise<{ passed: string[]; failed: ScenarioFailure[] }> {
   const shared: SanomaConfig = { ...config, databaseUrl, ledger: memoryLedger() };
   const resolved = resolveConfig(shared);
-  const { scenarios, errors } = await loadScenarios(resolved);
+  const { scenarios: loaded, errors } = await loadScenarios(resolved);
+  const scenarios = loaded.filter(isTest);
+  for (const s of loaded) if (!isTest(s)) log?.(`skipped ${s.file} › ${s.name}: ${s.moment ? "a moment" : "a world"}`);
   const failed: ScenarioFailure[] = errors.map(({ file, message }) => ({
     scenario: file,
     step: "did not load",
@@ -88,8 +103,9 @@ export async function runScenarios(
   const passed: string[] = [];
   if (scenarios.length === 0) return { passed, failed };
 
-  // Quiet: the scenarios call the fakes alone, so no vendor need be configured.
-  const worker = await startWorker(shared, { promote: true, quiet: true });
+  // Quiet: the scenarios call the fakes alone, so no vendor need be configured; and no schedule
+  // is applied, since a tick's run would be live.
+  const worker = await startWorker(shared, { promote: true, quiet: true, schedules: false });
   try {
     const client = await SanomaClient.connect(shared);
     try {