Switch to named function exports; last path segment is function name, rest is file path

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/0a6bcdff-fa2e-41bf-a254-313af4803268

Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Author: Copilot

.github/issue-proposals/apply-approach-1-function-injection.md

@@ -11,29 +11,29 @@ milestone:
 
 ## Summary
 
-Implement `.apply` as a plain TypeScript module that exports a single default function. When the command is run, Counterfact dynamically imports the file, calls the function, and passes the live REPL environment as arguments.
+Implement `.apply` as a plain TypeScript module that exports one or more named functions. When the command is run, Counterfact dynamically imports the file, looks up the named export matching the last path segment, calls that function, and passes the live REPL environment as its argument.
 
-This is the simplest possible design: no new abstractions, no DSL, and no framework. A script is just a function.
+This is the simplest possible design: no new abstractions, no DSL, and no framework. A script is just a named function.
 
 ---
 
 ## Design
 
 ### Script format
 
-An apply script is a TypeScript file with a default export:
+An apply script is a TypeScript file with one or more named function exports:
 
 ```ts
 // repl/sold-pets.ts
 import type { ApplyContext } from "counterfact";
 
-export default ($: ApplyContext) => {
+export function soldPets($: ApplyContext) {
   $.context.petService.reset();
   $.context.petService.addPet({ id: 1, status: "sold" });
   $.context.petService.addPet({ id: 2, status: "available" });
 
   $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
-};
+}
 ```
 
 ### The `ApplyContext` type
@@ -53,23 +53,20 @@ export interface ApplyContext {
 
 ### Invocation
 
+The argument to `.apply` is a slash-separated path. The last segment is the **function name** to call; everything before it is the **file path** (resolved relative to `<basePath>/repl/`, with `index.ts` as the default file):
+
 ```
-.apply sold-pets
-.apply path/to/sold-pets.ts
+.apply foo          # repl/index.ts  → foo($)
+.apply foo/bar      # repl/foo.ts    → bar($)
+.apply foo/bar/baz  # repl/foo/bar.ts → baz($)
 ```
 
-**Resolution order for named scenarios:**
-
-1. `<basePath>/repl/<name>.ts`
-2. `<basePath>/repl/<name>/index.ts`
-3. `<basePath>/<name>.ts` (direct path)
-
 ### Feedback output
 
 After execution, Counterfact compares the environment state before and after the script runs and prints a diff summary:
 
 ```
-Applied sold-pets
+Applied sold-pets/soldPets
 
 Routes added:
   getSoldPets
@@ -82,9 +79,9 @@ Context diffs are not automatically tracked in this approach — the script auth
 ## Implementation sketch
 
 1. Add `.apply` as a dot-command in `src/repl/repl.ts`.
-2. Resolve the file path using the ordered lookup above.
+2. Split the argument on `/`: the last segment is the function name; the rest form the file path.
 3. Dynamically import the resolved module (using `tsx` or the existing transpiler if the file is TypeScript).
-4. Call the exported function with the live environment objects.
+4. Look up the named export matching the function name and call it with the live environment objects.
 5. Snapshot `routes` before/after and print the diff.
 
 ---
@@ -103,9 +100,10 @@ Context diffs are not automatically tracked in this approach — the script auth
 
 ## Acceptance criteria
 
-- [ ] `.apply <name>` resolves and executes a TypeScript file from the configured `repl/` directory
-- [ ] `.apply <path>` resolves and executes a TypeScript file at the given relative path
-- [ ] The script receives `$` with `{ context, loadContext, routes, route }` as properties
+- [ ] `.apply foo` resolves `repl/index.ts` and calls the exported `foo` function
+- [ ] `.apply foo/bar` resolves `repl/foo.ts` and calls the exported `bar` function
+- [ ] `.apply foo/bar/baz` resolves `repl/foo/bar.ts` and calls the exported `baz` function
+- [ ] The function receives `$` with `{ context, loadContext, routes, route }` as properties
 - [ ] Routes injected by the script are available in the REPL after the command runs
 - [ ] The REPL prints a summary of routes added and removed after each apply
 - [ ] A meaningful error is shown when the file cannot be found or the export is not a function

.github/issue-proposals/apply-approach-2-scenario-class-lifecycle.md

@@ -11,21 +11,21 @@ milestone:
 
 ## Summary
 
-Implement `.apply` using a `Scenario` class interface with explicit `setup()` and `teardown()` lifecycle hooks, plus optional `dependencies` declaration. This approach adds structure for scenarios that need cleanup and enables dependency-ordered composition.
+Implement `.apply` using a `Scenario` class interface with explicit `setup()` and `teardown()` lifecycle hooks, plus optional `dependencies` declaration. Classes are exported by name — the last segment of the `.apply` path selects the named export, and Counterfact instantiates it automatically. This approach adds structure for scenarios that need cleanup and enables dependency-ordered composition.
 
 ---
 
 ## Design
 
 ### Script format
 
-A scenario is a class that implements the `Scenario` interface:
+A scenario is a named class export that implements the `Scenario` interface:
 
 ```ts
 // repl/sold-pets.ts
 import type { Scenario, ApplyContext } from "counterfact";
 
-export default class SoldPetsScenario implements Scenario {
+export class soldPets implements Scenario {
   static dependencies = ["base"];
 
   setup($: ApplyContext): void {
@@ -62,20 +62,23 @@ export interface Scenario {
 
 ### Invocation
 
+The same path/name convention as Approach 1 applies. The last segment selects the named export; everything before it is the file path:
+
 ```
-.apply sold-pets           # apply a named scenario
-.unapply sold-pets         # tear down if teardown() is defined
-.apply base sold-pets      # apply multiple scenarios in order
+.apply foo              # repl/index.ts  → new foo().setup($)
+.apply foo/bar          # repl/foo.ts    → new bar().setup($)
+.unapply foo/bar        # repl/foo.ts    → new bar().teardown($)
+.apply base soldPets    # apply multiple scenarios in order
 ```
 
 ### Dependency resolution
 
 When a scenario declares `static dependencies`, Counterfact automatically applies each dependency in order before applying the requested scenario. If a dependency is already applied (tracked by name), it is skipped.
 
 ```
-⬣> .apply sold-pets
-# Counterfact first applies "base" (dependency), then "sold-pets"
-Applied base → sold-pets
+⬣> .apply sold-pets/soldPets
+# Counterfact first applies "base" (dependency), then "soldPets"
+Applied base → soldPets
 
 Routes added:
   getSoldPets
@@ -122,10 +125,11 @@ Applied scenarios:
 
 ## Acceptance criteria
 
-- [ ] `.apply <name>` resolves, instantiates, and calls `setup()` on the scenario class
+- [ ] `.apply foo/bar` resolves `repl/foo.ts`, instantiates `bar`, and calls `setup($)`
+- [ ] `.apply foo` resolves `repl/index.ts`, instantiates `foo`, and calls `setup($)`
 - [ ] Static `dependencies` are applied automatically before the target scenario
 - [ ] A dependency that is already applied is not re-applied
-- [ ] `.unapply <name>` calls `teardown()` on the applied scenario instance
+- [ ] `.unapply foo/bar` calls `teardown($)` on the stored `bar` instance
 - [ ] The REPL tracks and displays the stack of currently applied scenarios
 - [ ] Scenarios that do not declare `teardown()` are still valid and usable
 - [ ] A meaningful error is shown when a dependency cycle is detected

.github/issue-proposals/apply-approach-3-proxy-based-tracking.md

@@ -21,18 +21,18 @@ This approach maximises ergonomics for script authors: a script looks like ordin
 
 ### Script format
 
-A script is a plain TypeScript module with a default export function. The script receives the live environment objects and mutates them directly, with no special wrapper required:
+A script is a plain TypeScript module that exports one or more named functions. The script receives the live environment objects and mutates them directly, with no special wrapper required:
 
 ```ts
 // repl/sold-pets.ts
-export default ($) => {
+export function soldPets($) {
   $.context.petService.reset();
 
   $.context.petService.addPet({ id: 1, status: "sold" });
   $.context.petService.addPet({ id: 2, status: "available" });
 
   $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
-};
+}
 ```
 
 This is identical in surface syntax to Approach 1. The difference is internal: `$.context` and `$.routes` passed to the script are **transparent reactive proxies** of the live objects.
@@ -44,7 +44,8 @@ Before calling the script, Counterfact wraps each environment object in a `Proxy
 ```ts
 const tracked = trackChanges(liveContext);
 const trackedRoutes = trackChanges(liveRoutes);
-await script({ context: tracked.proxy, routes: trackedRoutes.proxy, route: createRouteFunction(...) });
+const fn = module[functionName]; // named export resolved from path
+await fn({ context: tracked.proxy, routes: trackedRoutes.proxy, route: createRouteFunction(...) });
 const report = { context: tracked.changes(), routes: trackedRoutes.changes() };
 ```
 
@@ -64,7 +65,7 @@ interface ChangeRecord {
 After the script runs, Counterfact automatically prints a diff derived from the recorded changes:
 
 ```
-Applied sold-pets
+Applied sold-pets/soldPets
 
 Context changes:
   petService.pets: [] → [{id:1,status:"sold"},{id:2,status:"available"}]
@@ -77,25 +78,24 @@ No manual annotation is required from the script author.
 
 ### Invocation
 
+The same path/name convention as Approach 1 applies:
+
 ```
-.apply sold-pets
-.apply path/to/sold-pets.ts
+.apply foo          # repl/index.ts  → foo($) with proxy-wrapped $
+.apply foo/bar      # repl/foo.ts    → bar($) with proxy-wrapped $
+.apply foo/bar/baz  # repl/foo/bar.ts → baz($) with proxy-wrapped $
 ```
 
-Resolution order is the same as Approach 1:
-
-1. `<basePath>/repl/<name>.ts`
-2. `<basePath>/repl/<name>/index.ts`
-3. `<basePath>/<name>.ts`
+Resolution is the same as Approach 1; the difference is purely in what is passed to the function.
 
 ---
 
 ## Implementation sketch
 
 1. Add `.apply` as a dot-command in `src/repl/repl.ts`.
-2. Resolve the file path.
+2. Split the argument on `/`: the last segment is the function name; the rest form the file path.
 3. Create proxy wrappers around `context` and `routes`.
-4. Dynamically import and call the script with the proxy-wrapped arguments.
+4. Dynamically import the module, look up the named export, and call it with the proxy-wrapped arguments.
 5. Collect the accumulated change records from the proxies.
 6. Print the formatted diff.
 
@@ -139,7 +139,7 @@ Deep (nested) change tracking can be implemented by returning a recursive proxy
 
 ## Acceptance criteria
 
-- [ ] `.apply <name>` resolves and executes a TypeScript file, passing proxy-wrapped environment objects
+- [ ] `.apply foo/bar` resolves `repl/foo.ts`, calls `bar($)` with proxy-wrapped environment objects
 - [ ] All top-level property assignments to `context` are captured in the change log
 - [ ] Nested property mutations (e.g. `context.petService.reset()`) are captured where feasible
 - [ ] `$.routes.name = builder` assignments and `delete $.routes.name` are captured and reported