@mercury-fw/cli 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @mercury-fw/cli
 
+## 0.38.0
+
+### Minor Changes
+
+- de1ee52: Several people talking at once.
+
+  - `@mercury-fw/core`: turns of one conversation run one after the other, on every channel. Before, two HTTP `/turn` on the same conversation id ran together and mixed up its history.
+  - `@mercury-fw/core`: a turn waiting behind another one on the same conversation is dropped as soon as its client goes away.
+  - `@mercury-fw/core`: the idle capture waits for a running turn before it closes a conversation, and a sweep never starts while the previous one is still running.
+  - `@mercury-fw/core`: the capture a history compression triggers no longer leaves the capture marker wrong, which could make a later capture take the same messages twice or skip new ones.
+  - `@mercury-fw/core`: the tool log is kept per person, so a busy person no longer pushes everyone else's calls out of it.
+  - `@mercury-fw/core`: consolidation, `index.md` updates and confirmed promotions compare against the current file in the same queue as the write, so a concurrent update is never lost.
+  - `@mercury-fw/core`: vault files are written through a temporary file and a rename, so a reader never sees one half written.
+  - `@mercury-fw/core`: a vault file that exists but can't be read fails a write that depends on it, instead of counting as missing.
+  - `@mercury-fw/core`: the nightly review rewrites or deletes only the version of a document it read, and rereads it when it changed meanwhile.
+  - `@mercury-fw/core`: each pass of the nightly review gets up to 100 steps, up from 15.
+  - `@mercury-fw/cli`: an e2e case on HTTP can send its turns in `lanes` that run at the same time, each as its own user, on a conversation of its own or one they share.
+
+### Patch Changes
+
+- Updated dependencies [de1ee52]
+  - @mercury-fw/core@0.38.0
+  - @mercury-fw/utils@0.38.0
+
 ## 0.37.0
 
 ### Minor Changes

package/README.md

@@ -316,6 +316,23 @@ export default e2e({
 
 Each run of an HTTP case is a conversation of its own. A turn also has the response's `status` (200, or 401 for a refused token). The event stream carries no tool results, so on HTTP a call's `input` is the line the surface shows for it (the command, for a CLI tool) and its `output` is there only for a call staged for confirmation, with the token, as on the REPL. A turn may span several lines.
 
+To see what happens when people talk at the same time, an HTTP case can have `lanes` instead of `turns`: every lane sends its own turns in order, as its own user (`as`, or the case's), while the other lanes send theirs. Each lane gets a conversation of its own, unless lanes name the same `conversation`, which sends their turns at once on one conversation id, like two tabs on one chat. In the check, `run.lanes` holds each lane's run, and `run.turns` every turn, lane by lane:
+
+```ts
+{
+  name: "Alice and Bob at once",
+  channel: "http",
+  lanes: [
+    { as: "alice", turns: ["Remember: tamarind. Reply OK.", "What word did I give you?"] },
+    { as: "bob", turns: ["Remember: persimmon. Reply OK.", "What word did I give you?"] },
+  ],
+  check: (run, expect) => {
+    expect.that("Alice gets hers", run.lanes![0]!.last.answer.includes("tamarind"));
+    expect.that("Bob gets his", run.lanes![1]!.last.answer.includes("persimmon"));
+  },
+}
+```
+
 `before`, `after` and `check` also get `cli(command)`, which runs `sh -c command` in the app's container, outside the model, and resolves to its exit code and output: to prepare data (an issue to work on, a note in the wiki with the vault CLI), to check what a turn changed (`jira issue get KEY --select fields.assignee.displayName` after an assignment), to clean up. `after` runs even when the run or the check failed. A test that changes an external system has to clean up after itself, so start from read-only ones.
 
 #### What it can and can't test

package/dist/src/e2e/define.d.ts

@@ -4,7 +4,8 @@
  * app must have, and cases of turns sent to the app's real model, each with
  * checks on the calls it made and the answer it gave. A case talks to the
  * app's REPL, or to its HTTP surface as one of the test's users (each a token
- * the app's auth provider knows). `mfw e2e` runs them (`runner.ts`).
+ * the app's auth provider knows), possibly in lanes that run at the same time.
+ * `mfw e2e` runs them (`runner.ts`).
  */
 import type { Call, TurnData } from "./dump.ts";
 export type { Call } from "./dump.ts";
@@ -18,10 +19,13 @@ export type Turn = TurnData & {
     seconds: number;
     status?: number;
 };
-/** A case's run: every turn in order, and the last one. */
+/** A case's run: every turn in order, and the last one. A case in lanes
+ * also has each lane's own run; its `turns` are the lanes' turns, lane by
+ * lane, and `last` the last lane's last turn. */
 export type Run = {
     turns: Turn[];
     last: Turn;
+    lanes?: Run[];
 };
 /** Runs `command` in the app's container (`sh -c`), outside the model:
  * preparing data, reading what a turn changed, cleaning up. */
@@ -57,8 +61,23 @@ export type Expect = {
 };
 /** A turn's text: a message, or a function of the turn before (a follow-up, a confirmation token). */
 export type TurnText = string | ((previous: Turn) => string);
+/** A case's turns, each as text or as text with its own user. */
+export type Turns = Array<TurnText | {
+    text: TurnText;
+    as: string;
+}>;
+/** One of a case's lanes: turns sent in order, while the other lanes send
+ * theirs at the same time. */
+export type Lane = {
+    /** The user the lane's turns are sent as; the case's when absent. */
+    as?: string;
+    /** Lanes naming the same conversation send their turns on one HTTP
+     * conversation (two tabs on one chat); a lane without one gets its own. */
+    conversation?: string;
+    turns: Turns;
+};
 /** One case: the turns sent, in one session (one REPL, or one HTTP
- * conversation), and the checks on them. */
+ * conversation), or lanes of turns at the same time, and the checks on them. */
 export type E2eCase = {
     name: string;
     /** Where the turns go: the REPL (the default) or the HTTP surface, which
@@ -69,10 +88,10 @@ export type E2eCase = {
     /** The turns; on HTTP one can name its own user, so a case can stage an
      * action as one person and try to confirm it as another, in the same
      * conversation id. */
-    turns: Array<TurnText | {
-        text: TurnText;
-        as: string;
-    }>;
+    turns?: Turns;
+    /** On HTTP, instead of `turns`: lanes that run at the same time, to see
+     * what several users, or one user twice, get when they talk at once. */
+    lanes?: Lane[];
     /** How many times to run it (the model isn't deterministic); default 1. */
     repeat?: number;
     /** How many runs must pass; default every one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.37.0",
-    "@mercury-fw/utils": "0.37.0",
+    "@mercury-fw/core": "0.38.0",
+    "@mercury-fw/utils": "0.38.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
@@ -50,7 +50,7 @@
     "@mercury-fw/channel-http": "0.4.0",
     "@mercury-fw/auth-oidc": "0.1.0",
     "@mercury-fw/auth-static": "0.1.0",
-    "@mercury-fw/formatter": "0.37.0",
+    "@mercury-fw/formatter": "0.38.0",
     "@mercury-fw/plugin-atlassian-admin": "0.1.2",
     "@mercury-fw/plugin-bitbucket": "0.1.2",
     "@mercury-fw/plugin-jira": "0.4.3",

package/src/e2e/define.ts

@@ -4,7 +4,8 @@
  * app must have, and cases of turns sent to the app's real model, each with
  * checks on the calls it made and the answer it gave. A case talks to the
  * app's REPL, or to its HTTP surface as one of the test's users (each a token
- * the app's auth provider knows). `mfw e2e` runs them (`runner.ts`).
+ * the app's auth provider knows), possibly in lanes that run at the same time.
+ * `mfw e2e` runs them (`runner.ts`).
  */
 import type { Call, TurnData } from "./dump.ts";
 
@@ -18,8 +19,10 @@ export type { Call } from "./dump.ts";
  * no tool results. */
 export type Turn = TurnData & { seconds: number; status?: number };
 
-/** A case's run: every turn in order, and the last one. */
-export type Run = { turns: Turn[]; last: Turn };
+/** A case's run: every turn in order, and the last one. A case in lanes
+ * also has each lane's own run; its `turns` are the lanes' turns, lane by
+ * lane, and `last` the last lane's last turn. */
+export type Run = { turns: Turn[]; last: Turn; lanes?: Run[] };
 
 /** Runs `command` in the app's container (`sh -c`), outside the model:
  * preparing data, reading what a turn changed, cleaning up. */
@@ -51,8 +54,22 @@ export type Expect = {
 /** A turn's text: a message, or a function of the turn before (a follow-up, a confirmation token). */
 export type TurnText = string | ((previous: Turn) => string);
 
+/** A case's turns, each as text or as text with its own user. */
+export type Turns = Array<TurnText | { text: TurnText; as: string }>;
+
+/** One of a case's lanes: turns sent in order, while the other lanes send
+ * theirs at the same time. */
+export type Lane = {
+  /** The user the lane's turns are sent as; the case's when absent. */
+  as?: string;
+  /** Lanes naming the same conversation send their turns on one HTTP
+   * conversation (two tabs on one chat); a lane without one gets its own. */
+  conversation?: string;
+  turns: Turns;
+};
+
 /** One case: the turns sent, in one session (one REPL, or one HTTP
- * conversation), and the checks on them. */
+ * conversation), or lanes of turns at the same time, and the checks on them. */
 export type E2eCase = {
   name: string;
   /** Where the turns go: the REPL (the default) or the HTTP surface, which
@@ -63,7 +80,10 @@ export type E2eCase = {
   /** The turns; on HTTP one can name its own user, so a case can stage an
    * action as one person and try to confirm it as another, in the same
    * conversation id. */
-  turns: Array<TurnText | { text: TurnText; as: string }>;
+  turns?: Turns;
+  /** On HTTP, instead of `turns`: lanes that run at the same time, to see
+   * what several users, or one user twice, get when they talk at once. */
+  lanes?: Lane[];
   /** How many times to run it (the model isn't deterministic); default 1. */
   repeat?: number;
   /** How many runs must pass; default every one. */

package/src/e2e/load.ts

@@ -27,7 +27,15 @@ export async function loadTest(file: string): Promise<E2eTest> {
   for (const [i, c] of loaded.cases.entries()) {
     const which = `${file}: case ${i + 1} ("${c?.name ?? "?"}")`;
     if (typeof c?.name !== "string") throw new Error(`${which} has no name`);
-    if (!Array.isArray(c.turns) || c.turns.length === 0) throw new Error(`${which} has no turns`);
+    const nonEmpty = (list: unknown) => Array.isArray(list) && list.length > 0;
+    if (c.turns !== undefined && c.lanes !== undefined) throw new Error(`${which} has both turns and lanes`);
+    if (c.lanes !== undefined) {
+      if (c.channel !== "http") throw new Error(`${which} has lanes, which go with channel "http"`);
+      if (!nonEmpty(c.lanes)) throw new Error(`${which} has no turns`);
+      for (const [j, lane] of c.lanes.entries()) {
+        if (!nonEmpty(lane?.turns)) throw new Error(`${which} lane ${j + 1} has no turns`);
+      }
+    } else if (!nonEmpty(c.turns)) throw new Error(`${which} has no turns`);
     if (typeof c.check !== "function") throw new Error(`${which} has no check`);
     const whole = (n: unknown) => typeof n === "number" && Number.isInteger(n) && n >= 1;
     if (c.repeat !== undefined && !whole(c.repeat)) throw new Error(`${which} repeat takes a positive whole number`);

package/src/e2e/runner.ts

@@ -1,14 +1,15 @@
 /**
  * Runs e2e tests against an app: for each case (as many times as it
  * repeats), a fresh session (the REPL, or one conversation on the HTTP
- * surface) gets the case's turns, the checks run on what each turn did, and
+ * surface) gets the case's turns, or each of its lanes gets a session and
+ * they all send their turns at once; the checks run on what each turn did, and
  * every check is printed; the exit code says whether every case passed enough
  * runs. The sessions, the container commands and the report's destination are
  * injected (`session.ts`, `http-session.ts` and `commands.ts` hold the real
  * ones), so the tests drive the runner with scripted turns.
  */
 import { CATALOG } from "../catalog.ts";
-import type { Context, E2eCase, E2eTest, Run, Turn } from "./define.ts";
+import type { Context, E2eCase, E2eTest, Run, Turn, Turns, TurnText } from "./define.ts";
 import { turnFromDump, type TurnData } from "./dump.ts";
 import { createExpect, type Check } from "./expect.ts";
 
@@ -137,40 +138,96 @@ function tokenFor(channel: Channel, user: string | undefined, users: Record<stri
   return token;
 }
 
-/** One run of a case in a fresh session: `before`, the turns, the checks, `after`. */
+/** A turn ready to send: its text, and the token its user goes with. */
+type PlannedTurn = { text: TurnText; token: string | undefined };
+
+/** Settles every turn's user (the turn's own, or `user`) before anything is
+ * sent, so a case that doesn't add up costs nothing. */
+function plan(turns: Turns, channel: Channel, user: string | undefined, users: Record<string, string>): PlannedTurn[] {
+  return turns.map((next) => {
+    const { text, as } = typeof next === "object" ? next : { text: next, as: undefined };
+    return { text, token: tokenFor(channel, as ?? user, users) };
+  });
+}
+
+/** Sends `planned` on `session` one after the other, pushing each turn onto
+ * `turns` as it comes back (a function turn sees the one before it there). */
+async function sendTurns(session: Session, planned: PlannedTurn[], channel: Channel, turns: Turn[], deps: RunnerDeps): Promise<void> {
+  for (const { text, token } of planned) {
+    const line = typeof text === "string" ? text : text(turns.at(-1)!);
+    if (channel === "repl" && line.includes("\n")) throw new Error("a turn must be one line (the REPL reads one line per turn)");
+    const start = deps.now();
+    const reply = await session.turn(line, token);
+    const seconds = (deps.now() - start) / 1000;
+    if ("status" in reply) {
+      turns.push({ ...reply.turn, seconds, status: reply.status });
+      continue;
+    }
+    const data = turnFromDump(reply.dump);
+    const answer = data.calls.length === 0 && data.answer === "" ? answerFromOutput(reply.output) : data.answer;
+    turns.push({ calls: data.calls, answer, seconds });
+  }
+}
+
+/** Runs a case's lanes at the same time, each lane's turns in order, lanes
+ * naming the same conversation on one session; returns each lane's turns,
+ * filled in as they come back. */
+async function runLanes(
+  c: E2eCase,
+  channel: Channel,
+  users: Record<string, string>,
+  laneTurns: Turn[][],
+  deps: RunnerDeps,
+): Promise<void> {
+  if (channel !== "http") throw new Error('"lanes" go with channel "http"');
+  const lanes = c.lanes!.map((lane) => ({ conversation: lane.conversation, planned: plan(lane.turns, channel, lane.as ?? c.as, users) }));
+  const opened: Session[] = [];
+  const byConversation = new Map<string, Session>();
+  try {
+    const sessions: Session[] = [];
+    for (const { conversation } of lanes) {
+      let session = conversation === undefined ? undefined : byConversation.get(conversation);
+      if (session === undefined) {
+        session = await deps.openSession(channel);
+        opened.push(session);
+        if (conversation !== undefined) byConversation.set(conversation, session);
+      }
+      sessions.push(session);
+    }
+    await Promise.all(lanes.map((lane, i) => sendTurns(sessions[i]!, lane.planned, channel, laneTurns[i]!, deps)));
+  } finally {
+    await Promise.all(opened.map((session) => session.close()));
+  }
+}
+
+/** One run of a case in a fresh session (or one per lane): `before`, the turns, the checks, `after`. */
 async function runOnce(c: E2eCase, users: Record<string, string>, deps: RunnerDeps): Promise<RunReport> {
   const channel: Channel = c.channel ?? "repl";
   const ctx: Context = { cli: deps.cli };
   const turns: Turn[] = [];
+  const laneTurns: Turn[][] = (c.lanes ?? []).map(() => []);
   let checks: Check[] = [];
   try {
     await c.before?.(ctx);
-    // Every turn's user is settled before the session opens, so a case that
-    // doesn't add up costs nothing.
-    const planned = c.turns.map((next) => {
-      const { text, as } = typeof next === "object" ? next : { text: next, as: undefined };
-      return { text, token: tokenFor(channel, as ?? c.as, users) };
-    });
-    const session = await deps.openSession(channel);
-    try {
-      for (const { text, token } of planned) {
-        const line = typeof text === "string" ? text : text(turns.at(-1)!);
-        if (channel === "repl" && line.includes("\n")) throw new Error("a turn must be one line (the REPL reads one line per turn)");
-        const start = deps.now();
-        const reply = await session.turn(line, token);
-        const seconds = (deps.now() - start) / 1000;
-        if ("status" in reply) {
-          turns.push({ ...reply.turn, seconds, status: reply.status });
-          continue;
-        }
-        const data = turnFromDump(reply.dump);
-        const answer = data.calls.length === 0 && data.answer === "" ? answerFromOutput(reply.output) : data.answer;
-        turns.push({ calls: data.calls, answer, seconds });
+    if ((c.turns === undefined) === (c.lanes === undefined)) throw new Error('a case has either "turns" or "lanes"');
+    let lanes: Run[] | undefined;
+    if (c.lanes !== undefined) {
+      try {
+        await runLanes(c, channel, users, laneTurns, deps);
+      } finally {
+        turns.push(...laneTurns.flat());
+      }
+      lanes = laneTurns.map((laneTurn) => ({ turns: laneTurn, last: laneTurn.at(-1)! }));
+    } else {
+      const planned = plan(c.turns!, channel, c.as, users);
+      const session = await deps.openSession(channel);
+      try {
+        await sendTurns(session, planned, channel, turns, deps);
+      } finally {
+        await session.close();
       }
-    } finally {
-      await session.close();
     }
-    const run: Run = { turns, last: turns.at(-1)! };
+    const run: Run = { turns, last: turns.at(-1)!, ...(lanes === undefined ? {} : { lanes }) };
     const recorder = createExpect(run);
     try {
       await c.check(run, recorder.expect, ctx);