repl: support group-qualified .scenario in multi-API sessions

.changeset/cruel-hoops-sneeze.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Support `.scenario <group> <path>` in multi-API REPL sessions while preserving single-runner syntax.

docs/features/repl.md

@@ -84,6 +84,12 @@ For more complex setups you can automate REPL interactions by writing _scenario
 ⬣> .scenario soldPets
 ```
 
+When running multiple APIs in one process, qualify the command with the API group:
+
+```bash
+⬣> .scenario billing soldPets
+```
+
 **Path resolution:** the argument to `.scenario` is a slash-separated path. The last segment is the function name; everything before it is the file path, resolved relative to `<basePath>/scenarios/` (with `index.ts` as the default file).
 
 | Command | File | Function |

src/cli/run.ts

@@ -123,7 +123,7 @@
       const optionSource = program.getOptionValueSource(key);
 
       if (optionSource !== "cli") {
         (options as Record<string, unknown>)[key] = value;
       }
     }
 
@@ -142,8 +142,6 @@
     // objects ({source, prefix, group}), it describes multiple API specs and
     // is passed directly to counterfact() as the `specs` argument.
 
-    console.log("options", options);
-
     const specs = normalizeSpecOption(options.spec);
 
     if (specs === undefined && typeof options.spec === "string") {
@@ -165,7 +163,7 @@
       )
     ) {
       for (const action of actions) {
         (options as Record<string, unknown>)[action] = true;
       }
     }
 
@@ -256,7 +254,6 @@
 
     const { start, startRepl } = await (async () => {
       try {
-        console.log("specs = ", specs);
         return await counterfact(config, specs);
       } catch (error) {
         process.stderr.write(

src/repl/repl.ts

@@ -423,10 +423,57 @@
 
   replServer.defineCommand("scenario", {
     async action(text: string) {
-      const parts = text.trim().split("/").filter(Boolean);
+      const trimmedText = text.trim();
+      const parsedArgs = trimmedText.split(/\s+/u).filter(Boolean);
+      const usage = isMultiApi
+        ? "usage: .scenario <group> <path>"
+        : "usage: .scenario <path>";
+      const { selectedBinding, scenarioPath } = (() => {
+        if (!isMultiApi) {
+          if (trimmedText === "") {
+            return { scenarioPath: undefined, selectedBinding: undefined };
+          }
+
+          return { scenarioPath: trimmedText, selectedBinding: rootBinding };
+        }
+
+        if (parsedArgs.length !== 2) {
+          return { scenarioPath: undefined, selectedBinding: undefined };
+        }
+
+        return {
+          scenarioPath: parsedArgs[1],
+          selectedBinding: groupedBindings.find(
+            (binding) => binding.key === parsedArgs[0],
+          ),
+        };
+      })();
+
+      if (selectedBinding === undefined || scenarioPath === undefined) {
+        if (
+          isMultiApi &&
+          scenarioPath !== undefined &&
+          selectedBinding === undefined
+        ) {
+          const groupName = parsedArgs[0] ?? "";
+          const availableGroups = groupedBindings.map((binding) => binding.key);
+
+          print(
+            `Error: Unknown API group "${groupName}". Available groups: ${availableGroups.join(", ")}`,
+          );
+        } else {
+          print(usage);
+        }
+
+        this.clearBufferedCommand();
+        this.displayPrompt();
+        return;
+      }
+
+      const parts = scenarioPath.split("/").filter(Boolean);
 
       if (parts.length === 0) {
-        print("usage: .scenario <path>");
+        print(usage);
         this.clearBufferedCommand();
         this.displayPrompt();
         return;
@@ -443,7 +490,7 @@
       const fileKey =
         parts.length === 1 ? "index" : parts.slice(0, -1).join("/");
 
-      const module = rootBinding.scenarioRegistry?.getModule(fileKey);
+      const module = selectedBinding.scenarioRegistry?.getModule(fileKey);
 
       if (module === undefined) {
         print(`Error: Could not find scenario file "${fileKey}"`);
@@ -452,7 +499,7 @@
         return;
       }
 
       const fn = module[functionName];
 
       if (typeof fn !== "function") {
         print(
@@ -464,13 +511,35 @@
       }
 
       try {
+        const selectedRoutes = isMultiApi
+          ? (
+              replServer.context["routes"] as Record<
+                string,
+                Record<string, unknown>
+              >
+            )[selectedBinding.key]
+          : (replServer.context["routes"] as Record<string, unknown>);
+
+        if (isMultiApi && selectedRoutes === undefined) {
+          print(
+            `Error: Could not resolve routes for API group "${selectedBinding.key}"`,
+          );
+          this.clearBufferedCommand();
+          this.displayPrompt();
+          return;
+        }
+
         const applyContext = {
-          context: replServer.context["context"] as Record<string, unknown>,
-          loadContext: replServer.context["loadContext"] as (
+          context: selectedBinding.contextRegistry.find("/") as Record<
+            string,
+            unknown
+          >,
+          loadContext: ((path: string) =>
+            selectedBinding.contextRegistry.find(path)) as (
             path: string,
           ) => Record<string, unknown>,
-          route: replServer.context["route"] as (path: string) => unknown,
-          routes: replServer.context["routes"] as Record<string, unknown>,
+          route: groupedRoute[selectedBinding.key] as (path: string) => unknown,
+          routes: selectedRoutes,
         };
 
         await (fn as (ctx: typeof applyContext) => Promise<void> | void)(
@@ -486,7 +555,9 @@
       this.displayPrompt();
     },
 
-    help: 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
+    help: isMultiApi
+      ? 'apply a scenario script (".scenario <group> <path>" calls the named export from that group\'s scenarios/)'
+      : 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
   });
 
   return replServer;

test/repl/repl.test.ts

@@ -455,6 +455,136 @@ describe("REPL", () => {
       ).toMatchObject({ path: "/pets" });
     });
 
+    it("supports `.scenario <group> <path>` in multi-API mode and binds that group's context", async () => {
+      const billingRegistry = new ScenarioRegistry();
+      const inventoryRegistry = new ScenarioRegistry();
+      const billingContextRegistry = new ContextRegistry();
+      const inventoryContextRegistry = new ContextRegistry();
+
+      billingRegistry.add("index", {
+        setup(ctx: {
+          context: Record<string, unknown>;
+          loadContext: (path: string) => Record<string, unknown>;
+          routes: Record<string, unknown>;
+        }) {
+          ctx.context["applied"] = "billing";
+          ctx.context["loaded"] = ctx.loadContext("/")["from"];
+          ctx.routes["routeFromScenario"] = "billing";
+        },
+      });
+      inventoryRegistry.add("index", {
+        setup(ctx: { context: Record<string, unknown> }) {
+          ctx.context["applied"] = "inventory";
+        },
+      });
+      billingContextRegistry.add("/", { from: "billing-root" });
+      inventoryContextRegistry.add("/", { from: "inventory-root" });
+
+      const { harness } = createHarness(undefined, [
+        {
+          contextRegistry: billingContextRegistry,
+          group: "billing",
+          registry: new Registry(),
+          scenarioRegistry: billingRegistry,
+        },
+        {
+          contextRegistry: inventoryContextRegistry,
+          group: "inventory",
+          registry: new Registry(),
+          scenarioRegistry: inventoryRegistry,
+        },
+      ]);
+
+      await harness.callAsync("scenario", "billing setup");
+
+      expect(harness.output).toContain("Applied billing setup");
+      expect(billingContextRegistry.find("/")).toMatchObject({
+        applied: "billing",
+        from: "billing-root",
+        loaded: "billing-root",
+      });
+      expect(inventoryContextRegistry.find("/")).toMatchObject({
+        from: "inventory-root",
+      });
+      expect(
+        (
+          harness.server.context["routes"] as Record<
+            string,
+            Record<string, unknown>
+          >
+        )["billing"],
+      ).toMatchObject({ routeFromScenario: "billing" });
+      expect(
+        (
+          harness.server.context["routes"] as Record<
+            string,
+            Record<string, unknown>
+          >
+        )["inventory"],
+      ).toEqual({});
+    });
+
+    it("keeps group contexts isolated when applying a scenario to another group", async () => {
+      const billingRegistry = new ScenarioRegistry();
+      const inventoryRegistry = new ScenarioRegistry();
+      const billingContextRegistry = new ContextRegistry();
+      const inventoryContextRegistry = new ContextRegistry();
+
+      billingRegistry.add("index", {
+        setup(ctx: { context: Record<string, unknown> }) {
+          ctx.context["applied"] = "billing";
+        },
+      });
+      inventoryRegistry.add("index", {
+        setup(ctx: {
+          context: Record<string, unknown>;
+          routes: Record<string, unknown>;
+        }) {
+          ctx.context["applied"] = "inventory";
+          ctx.routes["inventoryRoute"] = true;
+        },
+      });
+
+      const { harness } = createHarness(undefined, [
+        {
+          contextRegistry: billingContextRegistry,
+          group: "billing",
+          registry: new Registry(),
+          scenarioRegistry: billingRegistry,
+        },
+        {
+          contextRegistry: inventoryContextRegistry,
+          group: "inventory",
+          registry: new Registry(),
+          scenarioRegistry: inventoryRegistry,
+        },
+      ]);
+
+      await harness.callAsync("scenario", "inventory setup");
+
+      expect(harness.output).toContain("Applied inventory setup");
+      expect(billingContextRegistry.find("/")).toEqual({});
+      expect(inventoryContextRegistry.find("/")).toMatchObject({
+        applied: "inventory",
+      });
+      expect(
+        (
+          harness.server.context["routes"] as Record<
+            string,
+            Record<string, unknown>
+          >
+        )["billing"],
+      ).toEqual({});
+      expect(
+        (
+          harness.server.context["routes"] as Record<
+            string,
+            Record<string, unknown>
+          >
+        )["inventory"],
+      ).toMatchObject({ inventoryRoute: true });
+    });
+
     it("shows an error when the scenario file is not in the registry", async () => {
       const scenarioRegistry = new ScenarioRegistry();
       const { harness } = createHarness(scenarioRegistry);
@@ -491,6 +621,58 @@ describe("REPL", () => {
       expect(harness.isReset()).toBe(true);
     });
 
+    it("shows an error with available groups for unknown group names in multi-api mode", async () => {
+      const { harness } = createHarness(undefined, [
+        {
+          contextRegistry: new ContextRegistry(),
+          group: "billing",
+          registry: new Registry(),
+          scenarioRegistry: new ScenarioRegistry(),
+        },
+        {
+          contextRegistry: new ContextRegistry(),
+          group: "inventory",
+          registry: new Registry(),
+          scenarioRegistry: new ScenarioRegistry(),
+        },
+      ]);
+
+      await harness.callAsync("scenario", "payments setup");
+
+      expect(harness.output[0]).toBe(
+        'Error: Unknown API group "payments". Available groups: billing, inventory',
+      );
+      expect(harness.isReset()).toBe(true);
+    });
+
+    it("shows multi-runner usage for missing or invalid arguments", async () => {
+      const { harness } = createHarness(undefined, [
+        {
+          contextRegistry: new ContextRegistry(),
+          group: "billing",
+          registry: new Registry(),
+          scenarioRegistry: new ScenarioRegistry(),
+        },
+        {
+          contextRegistry: new ContextRegistry(),
+          group: "inventory",
+          registry: new Registry(),
+          scenarioRegistry: new ScenarioRegistry(),
+        },
+      ]);
+
+      await harness.callAsync("scenario", "");
+      await harness.callAsync("scenario", "billing");
+      await harness.callAsync("scenario", "billing setup extra");
+
+      expect(harness.output).toEqual([
+        "usage: .scenario <group> <path>",
+        "usage: .scenario <group> <path>",
+        "usage: .scenario <group> <path>",
+      ]);
+      expect(harness.isReset()).toBe(true);
+    });
+
     it("rejects path traversal using '..' segments", async () => {
       const { harness } = createHarness();