You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/adr/001-apply-command-with-function-injection.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# ADR 001: .apply Command Design — Minimalist Function Injection
1
+
# ADR 001: .scenario Command Design — Minimalist Function Injection
2
2
3
3
## Status
4
4
@@ -8,7 +8,7 @@ Accepted
8
8
9
9
Counterfact's REPL lets developers interact with the running mock server from the terminal. A common need is to transition the server into a specific state (e.g. "all pets sold", "service unavailable") in a reproducible, shareable way. Today, operators must manually call REPL commands one by one; there is no mechanism to save and replay a named scenario.
10
10
11
-
The `.apply` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
11
+
The `.scenario` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
12
12
13
13
Three designs were proposed as working documents in `.github/issue-proposals/`:
14
14
@@ -27,7 +27,7 @@ Three designs were proposed as working documents in `.github/issue-proposals/`:
27
27
28
28
**Solution 1 (Minimalist Function Injection) is selected.**
29
29
30
-
An apply script is a TypeScript file with one or more named function exports. When `.apply <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:
30
+
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:
31
31
32
32
```ts
33
33
// repl/sold-pets.ts
@@ -55,7 +55,7 @@ Scripts export named functions that receive `$: ApplyContext`. Counterfact resol
55
55
56
56
### Solution 2: Scenario Class with Lifecycle Hooks
57
57
58
-
Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unapply`. A static `dependencies` array enables ordered composition.
58
+
Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unscenario`. A static `dependencies` array enables ordered composition.
59
59
60
60
**Why not chosen:** Class syntax and lifecycle coupling add complexity that is not justified until the need for teardown and dependency ordering is proven in practice. These concerns can be layered on top of Solution 1 once the basic command exists.
61
61
@@ -81,7 +81,7 @@ Identical surface syntax to Solution 1, but Counterfact wraps `context` and `rou
81
81
82
82
### Risks and downsides
83
83
84
-
- Without lifecycle hooks, accumulated state across many `.apply` calls may be difficult to reason about.
84
+
- Without lifecycle hooks, accumulated state across many `.scenario` calls may be difficult to reason about.
85
85
- If teardown proves to be a common need, adding it later will require extending the API in a backward-compatible way.
86
86
- Proxy-based auto-diffing (Solution 3) remains attractive for DX; deferring it means script authors will need to be disciplined about documenting context changes in the short term.
Copy file name to clipboardExpand all lines: docs/features/repl.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -56,21 +56,21 @@ await req.send()
56
56
57
57
See the [Route Builder guide](./route-builder.md) for full documentation.
58
58
59
-
## Scenario scripts with `.apply`
59
+
## Scenario scripts with `.scenario`
60
60
61
-
For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.apply`:
61
+
For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.scenario`:
62
62
63
63
```
64
-
⬣> .apply soldPets
64
+
⬣> .scenario soldPets
65
65
```
66
66
67
-
**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).
67
+
**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).
0 commit comments