@http-forge/core 0.4.6 → 0.4.8

package/README.md

@@ -252,6 +252,35 @@ if (pm.response.headers.has('Set-Cookie')) {
 }
 ```
 
+#### Response Body Type
+
+Like Postman, `pm.response.body` is the **raw response string** — it is not eagerly parsed. Parse JSON on demand:
+
+```javascript
+const data = pm.response.json();          // parsed object (null if not JSON)
+const text = pm.response.text();          // raw string
+const obj  = JSON.parse(pm.response.body); // body is a string
+```
+
+`json()` tolerates an already-parsed object body for backward compatibility, but new code should treat `pm.response.body` as a string.
+
+#### Legacy Postman Globals
+
+Older Postman scripts and many Newman-exported collections rely on bare globals from the pre-`pm.*` sandbox. The core injects these so legacy scripts run unchanged.
+
+Available in **both** pre-request and test scripts: `request` (`{ id, name, description, url, method, headers, data }`), `environment` (read snapshot), `globals` (read snapshot), `data` (iteration row), `iteration` (index), and `tv4` (`tv4.validate(data, schema)` — when the optional `tv4` module is installed).
+
+Available in **test** scripts only: `responseBody` (raw string), `responseCode` (`{ code, name, detail }`), `responseHeaders`, `responseTime`, `responseCookies` (`[{ name, value }]`), `tests` (`tests['name'] = boolean`), plus `postman.getResponseHeader(name)` and `postman.getResponseCookie(name)` (case-insensitive, return `null` if absent).
+
+```javascript
+// Legacy-style test script — runs unmodified
+tests['status 200'] = responseCode.code === 200;
+tests['has token'] = JSON.parse(responseBody).token !== undefined;
+tests['is json'] = /application\/json/.test(postman.getResponseHeader('Content-Type'));
+```
+
+> `environment` and `globals` are read snapshots — direct assignment was never persisted in legacy Postman either. Use `postman.setEnvironmentVariable()` / `postman.setGlobalVariable()` (or the modern `pm.environment.set()` / `pm.globals.set()`) to persist changes.
+
 #### Script Scope
 
 Control how script levels (collection → folder → request) and the pre-request/post-response phases share a JavaScript scope via `scripts.scope` in `http-forge.config.json` (or the `scriptScope` SDK option):
@@ -267,6 +296,31 @@ const forge = ForgeContainer.create({ scriptScope: 'isolated' });
 
 Use `'isolated'` when importing Postman collections whose scripts re-declare the same identifiers at multiple levels, which would otherwise throw `Identifier already declared` in shared mode.
 
+#### Async Script Execution (Event-Loop Draining)
+
+Like Postman, scripts do **not** end when their synchronous code returns. After the sync body completes, the core keeps the sandbox alive and drains pending timers (`setTimeout`/`setInterval`) and microtasks (un-awaited `Promise`s), then commits variable scopes — so deferred `pm.globals` / `pm.environment` / `pm.variables` writes are visible to the next request **without** `await`.
+
+```typescript
+// Post-response script — committed for the next request, no await required
+setTimeout(() => pm.globals.set('authToken', generateToken()), 1500);
+```
+
+The drain is bounded by `scripts.timeout` (the `scriptTimeout` SDK option), default **5000 ms**, which caps **both** synchronous CPU time and the async-drain window:
+
+```typescript
+const forge = ForgeContainer.create({ scriptTimeout: 10000 });
+```
+
+| Behavior | Notes |
+|----------|-------|
+| Sandbox kept alive after sync return | Pending timers/microtasks drained before the request advances |
+| Deferred `pm.*` writes committed | Visible to the next request without `await` |
+| Errors in timer/Promise callbacks | Reported as a console error, **non-fatal** — the request/test is not failed |
+| Runaway timers | A never-clearing `setInterval` or infinite timer loop is force-cancelled at the timeout, with a warning |
+| No async work | Returns immediately; draining adds no measurable latency |
+
+**Divergences from Postman:** uses real Node timers with a poll-based wall-clock drain (no exact pending-promise count, so pathological microtask recursion is bounded by the budget rather than a precise idle signal); a single `scripts.timeout` bounds both CPU time and the async window.
+
 ### Environment Management
 
 ```typescript
@@ -431,7 +485,7 @@ interface ForgeContainerOptions {
     
     // Script Settings
     scriptRunner?: IScriptRunner;    // Custom script runner
-    scriptTimeout?: number;          // Script timeout (ms)
+    scriptTimeout?: number;          // Script budget (ms); caps CPU time + async-drain window. Default 5000
     
     // History
     enableHistory?: boolean;         // Enable request history

package/dist/index.d.ts

@@ -20,6 +20,9 @@ export { ForgeContainer } from './container';
 export type { ForgeContainerOptions, StorageFormat } from './container';
 export { getServiceContainer, registerCoreServices, ServiceContainer, ServiceIdentifiers } from './di';
 export type { PlatformAdapters, ServiceIdentifier } from './di';
+export { buildCollectionToolDescription, buildCollectionToolName, buildFolderToolDescription, buildFolderToolName, buildRequestToolDescription, buildRequestToolName, buildSuiteToolDescription, buildSuiteToolName, mcpToolToken, parseMcpToolName, resolveFolderToken, resolveToken } from './runtime/mcp-tool-name';
+export type { McpToolKind, ParsedMcpToolName } from './runtime/mcp-tool-name';
+export { COLLECTION_INPUT_SCHEMA, FOLDER_INPUT_SCHEMA, REQUEST_INPUT_SCHEMA, SUITE_INPUT_SCHEMA } from './runtime/mcp-tool-schemas';
 export { createMcpRuntime, runCollection, runFolder, runRequest, runSuite } from './runtime/runtime-contracts';
 export type { McpRuntimeHandle, McpRuntimeOptions, RunCollectionOptions, RunRequestOptions, RunSuiteOptions } from './runtime/runtime-contracts';
 export { bootstrapNodeRuntime, createNodeContainer } from './runtime/node-bootstrap';