feat: implement .apply REPL dot-command (Approach 1: Minimalist Function Injection)

.changeset/apply-command.md

@@ -0,0 +1,17 @@
+---
+"counterfact": minor
+---
+
+Add `.apply` REPL dot-command (Approach 1: Minimalist Function Injection).
+
+The `.apply` command lets you run scenario scripts from the REPL prompt without leaving the terminal. A scenario is a plain TypeScript (or JavaScript) file that exports named functions. Each function receives an `ApplyContext` object with `{ context, loadContext, routes, route }` and can freely read or mutate state.
+
+**Path resolution:**
+
+| Command | File | Function |
+|---|---|---|
+| `.apply foo` | `scenarios/index.ts` | `foo` |
+| `.apply foo/bar` | `scenarios/foo.ts` | `bar` |
+| `.apply foo/bar/baz` | `scenarios/foo/bar.ts` | `baz` |
+
+The `ApplyContext` type is written to `types/apply-context.ts` during code generation.

docs/usage.md

@@ -498,6 +498,50 @@ await req.send()
 
 See the [Route Builder guide](./route-builder.md) for full documentation.
 
+### Scenario scripts with `.apply`
+
+For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.apply`:
+
+```
+⬣> .apply soldPets
+```
+
+**Path resolution:** the argument to `.apply` 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 |
+|---|---|---|
+| `.apply foo` | `scenarios/index.ts` | `foo` |
+| `.apply foo/bar` | `scenarios/foo.ts` | `bar` |
+| `.apply foo/bar/baz` | `scenarios/foo/bar.ts` | `baz` |
+
+A scenario function receives a single argument with `{ context, loadContext, routes, route }`:
+
+```ts
+// scenarios/index.ts
+import type { ApplyContext } from "../types/apply-context.js";
+
+export function soldPets(ctx: ApplyContext) {
+  // Mutate context directly — same as typing in the REPL
+  ctx.context.petService.reset();
+  ctx.context.petService.addPet({ id: 1, status: "sold" });
+  ctx.context.petService.addPet({ id: 2, status: "available" });
+
+  // Store a pre-configured route builder for later use in the REPL
+  ctx.routes.findSold = ctx
+    .route("/pet/findByStatus")
+    .method("get")
+    .query({ status: "sold" });
+}
+```
+
+After the command runs you can immediately use anything stored in `ctx.routes`:
+
+```js
+⬣> routes.findSold.send()
+```
+
+The `ApplyContext` type is generated automatically into `types/apply-context.ts` when you run Counterfact with type generation enabled.
+
 ---
 
 ## Proxy 🔀

src/repl/repl.ts

@@ -1,9 +1,12 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
 import repl from "node:repl";
 
 import type { Config } from "../server/config.js";
 import type { ContextRegistry } from "../server/context-registry.js";
 import type { OpenApiDocument } from "../server/dispatcher.js";
 import type { Registry } from "../server/registry.js";
+import { uncachedImport } from "../server/uncached-import.js";
 
 import { RawHttpClient } from "./raw-http-client.js";
 import { createRouteFunction } from "./route-builder.js";
@@ -214,5 +217,106 @@ export function startRepl(
     openApiDocument,
   );
 
+  replServer.context.routes = {};
+
+  replServer.defineCommand("apply", {
+    async action(text: string) {
+      const parts = text.trim().split("/").filter(Boolean);
+
+      if (parts.length === 0) {
+        print("usage: .apply <path>");
+        this.clearBufferedCommand();
+        this.displayPrompt();
+        return;
+      }
+
+      if (parts.some((part) => part === ".." || part === ".")) {
+        print("Error: Path must not contain '.' or '..' segments");
+        this.clearBufferedCommand();
+        this.displayPrompt();
+        return;
+      }
+
+      const functionName = parts[parts.length - 1] ?? "";
+      const fileParts = parts.slice(0, -1);
+      const scenariosDir = nodePath.join(config.basePath, "scenarios");
+      const fileBase =
+        fileParts.length > 0
+          ? nodePath.join(scenariosDir, ...fileParts)
+          : nodePath.join(scenariosDir, "index");
+
+      // Guard against path traversal: resolved path must stay within scenariosDir
+      const resolvedBase = nodePath.resolve(fileBase);
+      const resolvedScenariosDir = nodePath.resolve(scenariosDir);
+
+      if (
+        !resolvedBase.startsWith(resolvedScenariosDir + nodePath.sep) &&
+        resolvedBase !== resolvedScenariosDir
+      ) {
+        print("Error: Path must not escape the scenarios directory");
+        this.clearBufferedCommand();
+        this.displayPrompt();
+        return;
+      }
+
+      let filePath: string | undefined;
+
+      for (const ext of [".ts", ".js"]) {
+        const candidate = fileBase + ext;
+
+        try {
+          await fs.access(candidate);
+          filePath = candidate;
+          break;
+        } catch {
+          // file not found with this extension, try next
+        }
+      }
+
+      if (filePath === undefined) {
+        print(`Error: Could not find ${fileBase}.ts or ${fileBase}.js`);
+        this.clearBufferedCommand();
+        this.displayPrompt();
+        return;
+      }
+
+      try {
+        const mod = await uncachedImport(filePath);
+        const fn = (mod as Record<string, unknown>)[functionName];
+
+        if (typeof fn !== "function") {
+          print(
+            `Error: "${functionName}" is not a function exported from ${nodePath.relative(config.basePath, filePath)}`,
+          );
+          this.clearBufferedCommand();
+          this.displayPrompt();
+          return;
+        }
+
+        const applyContext = {
+          context: replServer.context["context"] as Record<string, unknown>,
+          loadContext: replServer.context["loadContext"] as (
+            path: string,
+          ) => Record<string, unknown>,
+          route: replServer.context["route"] as (path: string) => unknown,
+          routes: replServer.context["routes"] as Record<string, unknown>,
+        };
+
+        await (fn as (ctx: typeof applyContext) => Promise<void> | void)(
+          applyContext,
+        );
+
+        print(`Applied ${text.trim()}`);
+      } catch (error) {
+        print(`Error: ${String(error)}`);
+      }
+
+      this.clearBufferedCommand();
+      this.displayPrompt();
+    },
+
+    help: 'apply a scenario script (".apply <path>" calls the named export from scenarios/)',
+  });
+
   return replServer;
 }

src/typescript-generator/generate.ts

@@ -114,4 +114,66 @@ export async function generate(
   await repository.writeFiles(destination, generateOptions);
 
   debug("finished writing the files");
+
+  if (generateOptions.types) {
+    await writeApplyContextType(destination);
+    await writeDefaultScenariosIndex(destination);
+  }
+}
+
+const APPLY_CONTEXT_TYPE = `// This file is generated by Counterfact. Do not edit manually.
+import type { Context } from "../routes/_.context";
+
+export interface ApplyContext {
+  /** Root context, same as loadContext("/") */
+  context: Context;
+  /** Load a context object for a specific path */
+  loadContext: (path: string) => Record<string, unknown>;
+  /** Named route builders stored in the REPL execution context */
+  routes: Record<string, unknown>;
+  /** Create a new route builder for a given path */
+  route: (path: string) => unknown;
+}
+`;
+
+async function writeApplyContextType(destination: string): Promise<void> {
+  const typesDir = nodePath.join(destination, "types");
+  const filePath = nodePath.join(typesDir, "apply-context.ts");
+
+  await fs.mkdir(typesDir, { recursive: true });
+  await fs.writeFile(filePath, APPLY_CONTEXT_TYPE, "utf8");
+}
+
+const DEFAULT_SCENARIOS_INDEX = `import type { ApplyContext } from "../types/apply-context.js";
+
+// Scenario scripts are plain TypeScript functions that receive the live REPL
+// environment and can read or mutate server state. Run them from the REPL with:
+//   .apply <functionName>
+//
+// Example:
+// export function myScenario(ctx: ApplyContext) {
+//   // Read or mutate the root context (same object routes see as $.context)
+//   // ctx.context.<property> = <value>;
+//
+//   // Load a context for a specific path
+//   // const petsCtx = ctx.loadContext("/pets");
+//
+//   // Store a pre-configured route builder for later use in the REPL
+//   // ctx.routes.myRequest = ctx.route("/pets").method("get");
+// }
+//
+// Then in the REPL:
+//   .apply myScenario
+`;
+
+async function writeDefaultScenariosIndex(destination: string): Promise<void> {
+  const scenariosDir = nodePath.join(destination, "scenarios");
+  const filePath = nodePath.join(scenariosDir, "index.ts");
+
+  if (existsSync(filePath)) {
+    return;
+  }
+
+  await fs.mkdir(scenariosDir, { recursive: true });
+  await fs.writeFile(filePath, DEFAULT_SCENARIOS_INDEX, "utf8");
 }