@gcoredev/fastedge-test 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/bin/fastedge-debug.js +38 -3
  2. package/dist/lib/index.cjs +31 -13
  3. package/dist/lib/index.js +34 -14
  4. package/dist/lib/test-framework/index.cjs +31 -13
  5. package/dist/lib/test-framework/index.js +33 -14
  6. package/dist/lib/utils/fastedge-cli.d.ts +36 -1
  7. package/dist/server.js +27 -27
  8. package/docs/API.md +56 -56
  9. package/docs/DEBUGGER.md +31 -11
  10. package/docs/TEST_CONFIG.md +2 -2
  11. package/docs/TEST_FRAMEWORK.md +7 -7
  12. package/package.json +1 -1
package/docs/API.md CHANGED
@@ -18,12 +18,12 @@ The port can be overridden via the `PORT` environment variable. The active port
18
18
 
19
19
  The `POST /api/execute`, `POST /api/send`, and `POST /api/config` endpoints accept an optional `X-Source` request header that tags the origin of the operation in WebSocket broadcast events.
20
20
 
21
- | Value | Description |
22
- | ------------ | ------------------------------------------------------- |
23
- | `ui` | Request originated from the web UI (default if omitted) |
24
- | `ai_agent` | Request originated from an AI agent |
25
- | `api` | Request originated from direct API usage |
26
- | `system` | Request originated from an automated system |
21
+ | Value | Description |
22
+ | ---------- | ------------------------------------------------------- |
23
+ | `ui` | Request originated from the web UI (default if omitted) |
24
+ | `ai_agent` | Request originated from an AI agent |
25
+ | `api` | Request originated from direct API usage |
26
+ | `system` | Request originated from an automated system |
27
27
 
28
28
  ```http
29
29
  X-Source: ai_agent
@@ -179,11 +179,11 @@ curl -X POST http://localhost:5179/api/load \
179
179
 
180
180
  **Error Responses**
181
181
 
182
- | Status | Condition |
183
- | ------ | ------------------------------------------------------------------------------------------------------------ |
184
- | `400` | Validation failed, missing both `wasmPath` and `wasmBase64`, invalid path, or path does not end in `.wasm` |
185
- | `400` | `httpPort` is specified and already in use (HTTP-WASM only) |
186
- | `500` | WASM load failed or runner initialization error |
182
+ | Status | Condition |
183
+ | ------ | ----------------------------------------------------------------------------------------------------------- |
184
+ | `400` | Validation failed, missing both `wasmPath` and `wasmBase64`, invalid path, or path does not end in `.wasm` |
185
+ | `400` | `httpPort` is specified and already in use (HTTP-WASM only) |
186
+ | `500` | WASM load failed or runner initialization error |
187
187
 
188
188
  ---
189
189
 
@@ -417,10 +417,10 @@ curl -X POST http://localhost:5179/api/execute \
417
417
 
418
418
  **Error Responses**
419
419
 
420
- | Status | Condition |
421
- | ------ | ----------------------------------------------------------------------------------------------- |
422
- | `400` | No WASM module loaded, or missing `path`/`url` for HTTP-WASM, or missing `url` for Proxy-WASM |
423
- | `500` | Execution failed |
420
+ | Status | Condition |
421
+ | ------ | ---------------------------------------------------------------------------------------------- |
422
+ | `400` | No WASM module loaded, or missing `path`/`url` for HTTP-WASM, or missing `url` for Proxy-WASM |
423
+ | `500` | Execution failed |
424
424
 
425
425
  ---
426
426
 
@@ -529,10 +529,10 @@ curl -X POST http://localhost:5179/api/call \
529
529
 
530
530
  **Error Responses**
531
531
 
532
- | Status | Condition |
533
- | ------ | --------------------------------------------------------------------------------------- |
534
- | `400` | Validation failed (invalid hook name, missing `properties`), or no WASM module loaded |
535
- | `500` | Hook execution failed |
532
+ | Status | Condition |
533
+ | ------ | -------------------------------------------------------------------------------------- |
534
+ | `400` | Validation failed (invalid hook name, missing `properties`), or no WASM module loaded |
535
+ | `500` | Hook execution failed |
536
536
 
537
537
  ---
538
538
 
@@ -652,10 +652,10 @@ curl -X POST http://localhost:5179/api/send \
652
652
 
653
653
  **Error Responses**
654
654
 
655
- | Status | Condition |
656
- | ------ | ----------------------------------------------------------------------------- |
657
- | `400` | Validation failed (missing `url` or `properties`), or no WASM module loaded |
658
- | `500` | Execution failed |
655
+ | Status | Condition |
656
+ | ------ | ---------------------------------------------------------------------------- |
657
+ | `400` | Validation failed (missing `url` or `properties`), or no WASM module loaded |
658
+ | `500` | Execution failed |
659
659
 
660
660
  ---
661
661
 
@@ -744,9 +744,9 @@ curl http://localhost:5179/api/config
744
744
 
745
745
  **Error Responses**
746
746
 
747
- | Status | Condition |
748
- | ------ | ------------------------------------------- |
749
- | `404` | `fastedge-config.test.json` does not exist |
747
+ | Status | Condition |
748
+ | ------ | ------------------------------------------ |
749
+ | `404` | `fastedge-config.test.json` does not exist |
750
750
 
751
751
  ---
752
752
 
@@ -805,10 +805,10 @@ curl -X POST http://localhost:5179/api/config \
805
805
 
806
806
  **Error Responses**
807
807
 
808
- | Status | Condition |
809
- | ------ | ---------------------------------------------------------------------------------------- |
810
- | `400` | Validation failed (missing `config.appType`, `config.request`, or `config.properties`) |
811
- | `500` | File write failed |
808
+ | Status | Condition |
809
+ | ------ | --------------------------------------------------------------------------------------- |
810
+ | `400` | Validation failed (missing `config.appType`, `config.request`, or `config.properties`) |
811
+ | `500` | File write failed |
812
812
 
813
813
  ---
814
814
 
@@ -863,10 +863,10 @@ curl -X POST http://localhost:5179/api/config/save-as \
863
863
 
864
864
  **Error Responses**
865
865
 
866
- | Status | Condition |
867
- | ------ | ---------------------------------------- |
868
- | `400` | Missing `config` or `filePath` |
869
- | `500` | File write or directory creation failed |
866
+ | Status | Condition |
867
+ | ------ | --------------------------------------- |
868
+ | `400` | Missing `config` or `filePath` |
869
+ | `500` | File write or directory creation failed |
870
870
 
871
871
  ---
872
872
 
@@ -886,23 +886,23 @@ Returns the JSON Schema document with `Content-Type: application/json`.
886
886
 
887
887
  #### Request Schemas
888
888
 
889
- | Name | Description |
890
- | -------------- | ------------------------------------------- |
891
- | `api-load` | Request body schema for `POST /api/load` |
892
- | `api-send` | Request body schema for `POST /api/send` |
893
- | `api-call` | Request body schema for `POST /api/call` |
894
- | `api-config` | Request body schema for `POST /api/config` |
889
+ | Name | Description |
890
+ | ------------ | ------------------------------------------ |
891
+ | `api-load` | Request body schema for `POST /api/load` |
892
+ | `api-send` | Request body schema for `POST /api/send` |
893
+ | `api-call` | Request body schema for `POST /api/call` |
894
+ | `api-config` | Request body schema for `POST /api/config` |
895
895
 
896
896
  #### Response / Type Schemas
897
897
 
898
- | Name | Description |
899
- | ----------------------- | -------------------------------------------------------------- |
900
- | `fastedge-config.test` | Schema for `fastedge-config.test.json` config files |
901
- | `hook-result` | Shape of a single `HookResult` object |
902
- | `hook-call` | Shape of a `HookCall` input object |
903
- | `full-flow-result` | Shape of the `FullFlowResult` returned by full-flow endpoints |
904
- | `http-request` | Shape of an `HttpRequest` for HTTP-WASM execution |
905
- | `http-response` | Shape of an `HttpResponse` returned by HTTP-WASM execution |
898
+ | Name | Description |
899
+ | ---------------------- | ------------------------------------------------------------- |
900
+ | `fastedge-config.test` | Schema for `fastedge-config.test.json` config files |
901
+ | `hook-result` | Shape of a single `HookResult` object |
902
+ | `hook-call` | Shape of a `HookCall` input object |
903
+ | `full-flow-result` | Shape of the `FullFlowResult` returned by full-flow endpoints |
904
+ | `http-request` | Shape of an `HttpRequest` for HTTP-WASM execution |
905
+ | `http-response` | Shape of an `HttpResponse` returned by HTTP-WASM execution |
906
906
 
907
907
  **Example**
908
908
 
@@ -932,9 +932,9 @@ curl http://localhost:5179/api/schema/fastedge-config.test
932
932
 
933
933
  **Error Responses**
934
934
 
935
- | Status | Condition |
936
- | ------ | ---------------------- |
937
- | `404` | Schema name not found |
935
+ | Status | Condition |
936
+ | ------ | --------------------- |
937
+ | `404` | Schema name not found |
938
938
 
939
939
  ---
940
940
 
@@ -953,11 +953,11 @@ When a request body fails schema validation (Zod), `error` is the flattened Zod
953
953
 
954
954
  **Common status codes**
955
955
 
956
- | Status | Meaning |
957
- | ------ | ---------------------------------------------------------------------------------------------- |
958
- | `400` | Invalid request body, missing required fields, or precondition not met (e.g. no WASM loaded) |
959
- | `404` | Resource not found (config file, schema file) |
960
- | `500` | Internal server error during execution or I/O |
956
+ | Status | Meaning |
957
+ | ------ | --------------------------------------------------------------------------------------------- |
958
+ | `400` | Invalid request body, missing required fields, or precondition not met (e.g. no WASM loaded) |
959
+ | `404` | Resource not found (config file, schema file) |
960
+ | `500` | Internal server error during execution or I/O |
961
961
 
962
962
  ---
963
963
 
package/docs/DEBUGGER.md CHANGED
@@ -4,18 +4,20 @@ Runs the FastEdge debugger HTTP server, which hosts the web UI, REST API, and We
4
4
 
5
5
  ## CLI Usage
6
6
 
7
- The package exposes a `fastedge-debug` binary. Run it with `npx` without installing:
7
+ The package exposes a single binary, `fastedge-debug`. Run it with `npx` after installing `@gcoredev/fastedge-test` in your project:
8
8
 
9
9
  ```bash
10
- npx @gcoredev/fastedge-test
10
+ npx fastedge-debug
11
11
  ```
12
12
 
13
- Or using the explicit binary name:
13
+ If the package isn't installed yet, the explicit form fetches and runs it in one shot:
14
14
 
15
15
  ```bash
16
- npx fastedge-debug
16
+ npx -p @gcoredev/fastedge-test fastedge-debug
17
17
  ```
18
18
 
19
+ > The shorthand `npx @gcoredev/fastedge-test` happens to work today because the package declares exactly one `bin` entry, and npx falls back to it when no name is given. Prefer the explicit `fastedge-debug` form — it stays correct if a second binary is ever added.
20
+
19
21
  Once started, the server listens on `http://localhost:5179` by default and logs the bound address to stderr.
20
22
 
21
23
  The CLI automatically discovers the workspace root by walking up from the current directory, looking first for an existing `.fastedge-debug/` directory, then for a `package.json` or `Cargo.toml`. The resolved root is used as the base for port file and configuration file placement. Pass a path as the first argument to anchor discovery to a specific starting location:
@@ -24,6 +26,24 @@ The CLI automatically discovers the workspace root by walking up from the curren
24
26
  npx fastedge-debug /path/to/my-app
25
27
  ```
26
28
 
29
+ ### `--project-dir <path>` (or `-C <path>`)
30
+
31
+ For setups where the CLI is invoked from a subdirectory of the project (for example, a Rust app with a `fastedge-test/` Node sandbox holding the debugger install), pass `--project-dir` to anchor workspace discovery at a different path:
32
+
33
+ ```bash
34
+ # From inside fastedge-test/, point the debugger at the parent project root
35
+ cd fastedge-test
36
+ npx fastedge-debug --project-dir ..
37
+ ```
38
+
39
+ The flag accepts both `--project-dir <path>` and `--project-dir=<path>`. `-C` is a short alias. The resolved path then drives `WORKSPACE_PATH` and all config / fixture / dotenv resolution that flows from it, exactly as if the user had invoked the CLI from that directory. The flag is stripped before any remaining positional arguments are forwarded to the server, so you can combine it with a fixture path or other options:
40
+
41
+ ```bash
42
+ npx fastedge-debug --project-dir .. ../fixtures/scenario-1.test.json
43
+ ```
44
+
45
+ When omitted, behavior is unchanged from prior versions — the positional argument or `process.cwd()` is used as the starting point.
46
+
27
47
  ## Programmatic Usage
28
48
 
29
49
  Import `startServer` from the `./server` export to start the server from your own script or test setup:
@@ -98,13 +118,13 @@ curl http://localhost:5179/health
98
118
 
99
119
  ## Environment Variables
100
120
 
101
- | Variable | Type | Default | Description |
102
- | -------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
103
- | `PORT` | `number` | unset | Port the HTTP server listens on. Defaults to `5179` when not set. |
104
- | `PROXY_RUNNER_DEBUG` | `"1"` | unset | Enable verbose debug logging for WebSocket and runner activity. |
105
- | `VSCODE_INTEGRATION` | `"true"` | unset | Set to `"true"` when running inside the VSCode extension; enables workspace WASM detection. |
106
- | `WORKSPACE_PATH` | `string` | unset | Absolute path to the workspace root; used as the `.env` file base and for port file placement. |
107
- | `FASTEDGE_RUN_PATH` | `string` | unset | Override the path to the `fastedge-run` CLI binary used to execute WASM modules. |
121
+ | Variable | Type | Default | Description |
122
+ | -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------- |
123
+ | `PORT` | `number` | unset | Port the HTTP server listens on. Defaults to `5179` when not set. |
124
+ | `PROXY_RUNNER_DEBUG` | `"1"` | unset | Enable verbose debug logging for WebSocket and runner activity. |
125
+ | `VSCODE_INTEGRATION` | `"true"` | unset | Set to `"true"` when running inside the VSCode extension; enables workspace WASM detection. |
126
+ | `WORKSPACE_PATH` | `string` | unset | Absolute path to the workspace root; used as the `.env` file base and for port file placement. |
127
+ | `FASTEDGE_RUN_PATH` | `string` | unset | Override the path to the `fastedge-run` CLI binary used to execute WASM modules. |
108
128
 
109
129
  ### Usage examples
110
130
 
package/docs/TEST_CONFIG.md CHANGED
@@ -27,12 +27,12 @@ The config schema is a union of two variants selected by `appType`:
27
27
  | `$schema` | `string` | No | — | URI pointing to the JSON Schema file for IDE autocompletion and validation. |
28
28
  | `description` | `string` | No | — | Human-readable label for this test scenario. |
29
29
  | `wasm` | `object` | No | — | WASM binary configuration. Required when running without a programmatic `wasmBuffer`. |
30
- | `wasm.path` | `string` | Yes (if `wasm` present) | — | Path to the compiled `.wasm` binary, relative to the config file or absolute. |
30
+ | `wasm.path` | `string` | Yes (if `wasm` present) | — | Path to the compiled `.wasm` binary, relative to the config file or absolute. |
31
31
  | `wasm.description` | `string` | No | — | Human-readable label for the WASM binary. |
32
32
  | `appType` | `string` | Yes (schema) / CDN has runtime default | `"proxy-wasm"` | App variant. `"proxy-wasm"` for CDN mode; `"http-wasm"` for HTTP mode. HTTP-WASM has no default. |
33
33
  | `request` | `object` | **Yes** | — | Incoming HTTP request to simulate. |
34
34
  | `request.method` | `string` | Yes (schema) / runtime default | `"GET"` | HTTP method (e.g. `"GET"`, `"POST"`). |
35
- | `request.url` | `string` | **Yes** (CDN only) | — | Full URL for the simulated upstream request (e.g. `"https://example.com/api"`). CDN mode only. |
35
+ | `request.url` | `string` | **Yes** (CDN only) | — | Full URL for the simulated upstream request (e.g. `"https://example.com/api"`). CDN mode only. |
36
36
  | `request.path` | `string` | **Yes** (HTTP-WASM only) | — | Request path (e.g. `"/api/submit"`). HTTP-WASM mode only. The WASM module acts as the origin server and receives only the path portion of the request. |
37
37
  | `request.headers` | `object` | Yes (schema) / runtime default | `{}` | Key/value map of request headers. All keys and values must be strings. |
38
38
  | `request.body` | `string` | Yes (schema) / runtime default | `""` | Request body as a plain string. Use an empty string for requests with no body. |
package/docs/TEST_FRAMEWORK.md CHANGED
@@ -195,13 +195,13 @@ interface RunnerConfig {
195
195
  }
196
196
  ```
197
197
 
198
- | Field | Type | Description |
199
- | -------------------------------- | ------------------------------ | ------------------------------------------------------------------------- |
200
- | `dotenv.enabled` | `boolean` | Enable dotenv loading |
201
- | `dotenv.path` | `string` | Directory to load dotenv files from; defaults to process CWD when omitted |
202
- | `enforceProductionPropertyRules` | `boolean` | Override production property enforcement for the runner; default `true` |
203
- | `runnerType` | `"http-wasm" \| "proxy-wasm"` | Override automatic WASM type detection |
204
- | `httpPort` | `number` | Pin the HTTP server to a specific port (HTTP WASM only; throws if in use) |
198
+ | Field | Type | Description |
199
+ | -------------------------------- | ------------------------------- | ------------------------------------------------------------------------- |
200
+ | `dotenv.enabled` | `boolean` | Enable dotenv loading |
201
+ | `dotenv.path` | `string` | Directory to load dotenv files from; defaults to process CWD when omitted |
202
+ | `enforceProductionPropertyRules` | `boolean` | Override production property enforcement for the runner; default `true` |
203
+ | `runnerType` | `"http-wasm" \| "proxy-wasm"` | Override automatic WASM type detection |
204
+ | `httpPort` | `number` | Pin the HTTP server to a specific port (HTTP WASM only; throws if in use) |
205
205
 
206
206
  ## Functions
207
207
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gcoredev/fastedge-test",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "private": false,
5
5
  "repository": {
6
6
  "type": "git",