refactor: rename ApplyContext to Scenario$

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/8351ae82-12ca-4eb9-9a15-ac0476683ab2

Author: Copilot

docs/adr/001-apply-command-with-function-injection.md

@@ -27,29 +27,29 @@ Three designs were proposed as working documents in `.github/issue-proposals/`:
 
 **Solution 1 (Minimalist Function Injection) is selected.**
 
-A scenario script is a TypeScript file with one or more named function exports. When `.scenario <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `ApplyContext` (`$`) object:
+A scenario script is a TypeScript file with one or more named function exports. When `.scenario <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `Scenario$` (`$`) object:
 
 ```ts
 // repl/sold-pets.ts
-import type { ApplyContext } from "counterfact";
+import type { Scenario$ } from "../types/scenario-context.js";
 
-export function soldPets($: ApplyContext) {
+export function soldPets($: Scenario$) {
   $.context.petService.reset();
   $.context.petService.addPet({ id: 1, status: "sold" });
 
   $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
 }
 ```
 
-`ApplyContext` exposes `{ context, loadContext, routes, route }`. After the function returns, Counterfact diffs the `routes` object and prints a summary of what was added or removed.
+`Scenario$` exposes `{ context, loadContext, routes, route }`. After the function returns, Counterfact diffs the `routes` object and prints a summary of what was added or removed.
 
 Solution 1 was chosen because it introduces the smallest possible API surface, imposes no structural requirements on script authors, and integrates naturally with TypeScript `import` for composability. It is the right foundation to build on before adding lifecycle or tracking features.
 
 ## Options
 
 ### Solution 1: Minimalist Function Injection (selected)
 
-Scripts export named functions that receive `$: ApplyContext`. Counterfact resolves the file/function from the path argument and calls the function directly. Route changes are diffed and reported; context changes are not automatically tracked.
+Scripts export named functions that receive `$: Scenario$`. Counterfact resolves the file/function from the path argument and calls the function directly. Route changes are diffed and reported; context changes are not automatically tracked.
 
 **Why chosen:** Maximum simplicity. No new abstractions, no required boilerplate. Easy to implement, test, and understand. Composability via normal `import`.
 
@@ -89,7 +89,7 @@ Identical surface syntax to Solution 1, but Counterfact wraps `context` and `rou
 
 - Evaluate whether `teardown` support (from Solution 2) is needed and, if so, define a clean extension point.
 - Explore adding proxy-based context diffing (from Solution 3) as an opt-in enhancement once the core command is stable.
-- Define `ApplyContext` as a public exported type in `counterfact-types/`.
+- Define `Scenario$` as a public exported type in `counterfact-types/`.
 
 ## Advice
 

docs/features/repl.md

@@ -98,7 +98,7 @@ After the command runs you can immediately use anything stored in `$.routes`:
 ⬣> routes.findSold.send()
 ```
 
-The `Scenario` type and `ApplyContext` interface are generated automatically into `types/scenario-context.ts` when you run Counterfact with type generation enabled.
+The `Scenario` type and `Scenario$` interface are generated automatically into `types/scenario-context.ts` when you run Counterfact with type generation enabled.
 
 ## Startup scenario
 
@@ -130,9 +130,9 @@ export const startup: Scenario = ($) => {
 
 ```ts
 // scenarios/pets.ts
-import type { ApplyContext } from "../types/scenario-context.js";
+import type { Scenario$ } from "../types/scenario-context.js";
 
-export function addPets($: ApplyContext, count: number, species: string) {
+export function addPets($: Scenario$, count: number, species: string) {
   for (let i = 0; i < count; i++) {
     $.context.addPet({ name: `${species} ${i + 1}`, status: "available", photoUrls: [] });
   }

docs/patterns/scenario-scripts.md

@@ -87,9 +87,9 @@ export const startup: Scenario = ($) => {
 
 ```ts
 // scenarios/pets.ts
-import type { ApplyContext } from "../types/scenario-context.js";
+import type { Scenario$ } from "../types/scenario-context.js";
 
-export function addPets($: ApplyContext, count: number, species: string) {
+export function addPets($: Scenario$, count: number, species: string) {
   for (let i = 0; i < count; i++) {
     $.context.addPet({
       name: `${species} ${i + 1}`,
@@ -102,9 +102,9 @@ export function addPets($: ApplyContext, count: number, species: string) {
 
 ```ts
 // scenarios/orders.ts
-import type { ApplyContext } from "../types/scenario-context.js";
+import type { Scenario$ } from "../types/scenario-context.js";
 
-export function addOrders($: ApplyContext, count: number) {
+export function addOrders($: Scenario$, count: number) {
   for (let i = 0; i < count; i++) {
     $.context.addOrder({ petId: i + 1, quantity: 1, status: "placed" });
   }

src/app.ts

@@ -16,12 +16,12 @@ import { Registry } from "./server/registry.js";
 import { ScenarioRegistry } from "./server/scenario-registry.js";
 import { Transpiler } from "./server/transpiler.js";
 import { CodeGenerator } from "./typescript-generator/code-generator.js";
-import { writeApplyContextType } from "./typescript-generator/generate.js";
+import { writeScenarioContextType } from "./typescript-generator/generate.js";
 import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
 
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
 
-type ApplyContext = {
+type Scenario$ = {
   context: Record<string, unknown>;
   loadContext: (path: string) => Record<string, unknown>;
   route: (path: string) => unknown;
@@ -40,16 +40,16 @@ export async function runStartupScenario(
     return;
   }
 
-  const applyContext: ApplyContext = {
+  const scenario$: Scenario$ = {
     context: contextRegistry.find("/") as Record<string, unknown>,
     loadContext: (path: string) =>
       contextRegistry.find(path) as Record<string, unknown>,
     route: createRouteFunction(config.port, "localhost", openApiDocument),
     routes: {},
   };
 
-  await (indexModule["startup"] as (ctx: ApplyContext) => Promise<void> | void)(
-    applyContext,
+  await (indexModule["startup"] as (ctx: Scenario$) => Promise<void> | void)(
+    scenario$,
   );
 }
 
@@ -221,7 +221,7 @@ export async function counterfact(config: Config) {
   );
 
   contextRegistry.addEventListener("context-changed", () => {
-    void writeApplyContextType(modulesPath);
+    void writeScenarioContextType(modulesPath);
   });
 
   const middleware = koaMiddleware(dispatcher, config);

src/typescript-generator/generate.ts

@@ -146,7 +146,7 @@ export async function generate(
   debug("finished writing the files");
 
   if (generateOptions.types) {
-    await writeApplyContextType(destination);
+    await writeScenarioContextType(destination);
     await writeDefaultScenariosIndex(destination);
   }
 }
@@ -251,7 +251,7 @@ function buildLoadContextOverload(routePath: string, alias: string): string {
   return `  loadContext(path: \`${templatePath}\`): ${alias};`;
 }
 
-function buildApplyContextContent(contextFiles: ContextFileInfo[]): string {
+function buildScenarioContextContent(contextFiles: ContextFileInfo[]): string {
   const rootContext = contextFiles.find((f) => f.routePath === "/");
   const contextType = rootContext
     ? rootContext.alias
@@ -271,7 +271,7 @@ function buildApplyContextContent(contextFiles: ContextFileInfo[]): string {
     "// This file is generated by Counterfact. Do not edit manually.",
     ...importLines,
     "",
-    "export interface ApplyContext {",
+    "export interface Scenario$ {",
     '  /** Root context, same as loadContext("/") */',
     `  context: ${contextType};`,
     "  /** Load a context object for a specific path */",
@@ -284,7 +284,7 @@ function buildApplyContextContent(contextFiles: ContextFileInfo[]): string {
     "}",
     "",
     "/** A scenario function that receives the live REPL environment */",
-    "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+    "export type Scenario = ($: Scenario$) => Promise<void> | void;",
     "",
   ];
 
@@ -293,22 +293,22 @@ function buildApplyContextContent(contextFiles: ContextFileInfo[]): string {
 
 /**
  * Writes the `types/scenario-context.ts` file, which exports the
- * `ApplyContext` interface used to type scenario functions.
+ * `Scenario$` interface used to type scenario functions.
  *
  * The interface is generated from all `_.context.ts` files found under the
  * `routes/` directory, providing strongly typed `loadContext()` overloads for
  * every route path that has a context file.
  *
  * @param destination - Root output directory.
  */
-export async function writeApplyContextType(
+export async function writeScenarioContextType(
   destination: string,
 ): Promise<void> {
   const typesDir = nodePath.join(destination, "types");
   const filePath = nodePath.join(typesDir, "scenario-context.ts");
 
   const contextFiles = await collectContextFiles(destination);
-  const content = buildApplyContextContent(contextFiles);
+  const content = buildScenarioContextContent(contextFiles);
 
   await fs.mkdir(typesDir, { recursive: true });
   await fs.writeFile(filePath, content, "utf8");

test/typescript-generator/generate.test.ts

@@ -78,7 +78,7 @@ describe("scenario-context type generation", () => {
       );
       expect(content).not.toContain("import type");
       expect(content).toContain(
-        "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+        "export type Scenario = ($: Scenario$) => Promise<void> | void;",
       );
     });
   });