docs: add a skill file for scripting feature bug fix

[ihexxa]

Summary

Adds a new Claude Code skill: .claude/skills/fix-scripting-feature/

• SKILL.md — Playbook for debugging Insomnia's pre-request/after-response/test scripting (pm/insomnia API). Documents:

  • The two execution paths (Electron hidden-window sandbox vs. inso CLI, no sandbox) and where each lives in the codebase
  • Folder map of insomnia-scripting-environment/src/objects/
  • A reproduce-with-narrowest-test procedure (unit → SDK → smoke tests)
  • Symptom → file lookup table (sandbox violations, missing modules, timeouts, hidden-window races, stale autocomplete snippets)

• references/objects/*.md (24 files) — One reference doc per SDK object source file (insomnia.md, request.md, response.md, environments.md, cookies.md, auth.md, urls.md, etc.), each covering public API, how scripts reach it, and gotchas.

[Copilot]

Pull request overview

Adds a Claude Code skill for debugging Insomnia scripting across execution paths and SDK objects.

Changes:

• Adds scripting architecture, reproduction, testing, and troubleshooting guidance.
• Adds 24 SDK object reference documents.
• Documents API behavior and implementation gotchas.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description and final review notes
.claude/skills/fix-scripting-feature/SKILL.md	Debugging playbook. Nits: (4 votes) describe tests as covering selected objects; (3 votes) document the opt-in QuickJS execution path.
.claude/skills/fix-scripting-feature/references/objects/variables.md	Variable/list APIs. No final comments.
.claude/skills/fix-scripting-feature/references/objects/utils.md	URL template helpers. No final comments.
.claude/skills/fix-scripting-feature/references/objects/urls.md	URL and match patterns. Nits: (3 votes) match remains a string and uses temporary matchers; (3 votes) bypass is a string[], not a UrlMatchPatternList.
.claude/skills/fix-scripting-feature/references/objects/test.md	Script test handling. No final comments.
.claude/skills/fix-scripting-feature/references/objects/send-request.md	Ad hoc request execution. No final comments.
.claude/skills/fix-scripting-feature/references/objects/response.md	Response APIs. Nits: (3 votes) dataURI() is not Base64-encoding the body in addition to the typo; (2 votes) response.to repeatedly registers a new Chai plugin callback.
.claude/skills/fix-scripting-feature/references/objects/request.md	Request and body APIs. No final comments.
.claude/skills/fix-scripting-feature/references/objects/request-info.md	Request metadata. No final comments.
.claude/skills/fix-scripting-feature/references/objects/README.md	Reference index. No final comments.
.claude/skills/fix-scripting-feature/references/objects/proxy-configs.md	Proxy configuration. Nit: (4 votes) enabled status uses the first non-empty proxy rather than the protocol-selected proxy.
.claude/skills/fix-scripting-feature/references/objects/properties.md	Base property/list APIs. Nit: (4 votes) upsert can drop the remaining suffix due to sequential splice mutations.
.claude/skills/fix-scripting-feature/references/objects/interpolator.md	Template interpolation. No final comments.
.claude/skills/fix-scripting-feature/references/objects/interfaces.md	Shared context types. Nit: (3 votes) RequestInfoOption and ExecutionOption are attributed to the wrong modules.
.claude/skills/fix-scripting-feature/references/objects/insomnia.md	Top-level scripting object. Nit: (2 votes) runtime proxies expose and allow mutation of TypeScript-private globals fields.
.claude/skills/fix-scripting-feature/references/objects/headers.md	Header APIs. No final comments.
.claude/skills/fix-scripting-feature/references/objects/folders.md	Folder hierarchy behavior. No final comments.
.claude/skills/fix-scripting-feature/references/objects/execution.md	Execution controls. No final comments.
.claude/skills/fix-scripting-feature/references/objects/environments.md	Environment and variable resolution. Nits: (2 votes) runtime proxies expose both private environment properties; (4 votes) precedence follows caller-supplied array order rather than always favoring the nearest folder.
.claude/skills/fix-scripting-feature/references/objects/cookies.md	Cookie APIs. No final comments.
.claude/skills/fix-scripting-feature/references/objects/console.md	Script console behavior. No final comments.
.claude/skills/fix-scripting-feature/references/objects/collection.md	Collection namespace exports. No final comments.
.claude/skills/fix-scripting-feature/references/objects/certificates.md	Client certificate API. Nits: (3 votes) fallback logging is warning-level; (2 votes) the first certificate is selected whenever matches are non-empty, including multiple matches.
.claude/skills/fix-scripting-feature/references/objects/auth.md	Authentication API. Nit: (2 votes) the privateKey gotcha is reversed; OAuth1 privateKey is written back by fromPreRequestAuth().
.claude/skills/fix-scripting-feature/references/objects/async-objects.md	Promise tracking behavior. Nit: (3 votes) async-function results are not guaranteed to become ProxiedPromise instances or be added to scriptPromises.

Suppressed comments (22)

.claude/skills/fix-scripting-feature/SKILL.md:69

• This repeats the one-page-per-source-file claim, but the barrel src/objects/index.ts has no references/objects/index.md. Qualify the scope to SDK object modules or add the missing reference page.

For property/method-level detail on any single object above (real signatures, script-facing surface, gotchas), see `references/objects/<name>.md` in this skill folder — one file per source file in `src/objects/` (e.g. `references/objects/request.md` for `request.ts`, `references/objects/environments.md` for `environments.ts`).

.claude/skills/fix-scripting-feature/SKILL.md:44

• collection.ts is not a Collection implementation or the variable-resolution module. It is only a re-export barrel; directing a debugger here for pm.collectionVariables or folder resolution sends them to the wrong file. Point this entry at the namespace re-exports and refer to environments.ts/insomnia.ts for storage and wiring.

│   │   ├── collection.ts          # Collection — pm.collectionVariables / folder & collection variable resolution

.claude/skills/fix-scripting-feature/references/objects/README.md:3

• This says there is one document for every source file, but src/objects/index.ts is a source file with no corresponding references/objects/index.md. Either add that page or qualify this statement to exclude the barrel file.

One doc per source file in `packages/insomnia-scripting-environment/src/objects/`. Each covers: public API (real signatures), how a script actually reaches it (`pm.*`/`insomnia.*`), and gotchas found while reading the code.

.claude/skills/fix-scripting-feature/references/objects/README.md:43

• The index repeats the incomplete dataURI() description: fixing only baseg4 would still leave raw, non-Base64 body data in the URI. Include the missing encoding defect here too so the quick-reference gotcha does not understate the problem.

- `Response.dataURI()` has a typo bug: emits `baseg4` instead of `base64` — see `response.md`.

.claude/skills/fix-scripting-feature/references/objects/certificates.md:34

• The documented conflict behavior is reversed: mergeClientCertificates takes the PFX branch whenever pfx.src is non-empty, even when cert and key are also present. It throws only when a non-empty certificate has neither a usable PFX nor a complete non-empty cert/key pair.

- **`cert+key` and `pfx` are mutually exclusive downstream.** `request.ts`'s `mergeClientCertificates` throws `Error('Invalid certificate configuration: "cert+key" and "pfx" can not be set at the same time')` if a script sets both a PFX and a cert/key pair on `pm.request.certificate`.

.claude/skills/fix-scripting-feature/references/objects/collection.md:36

• This says the index.ts file carries the same top-level JSDoc block, but index.ts is only the export statements and has no such comment. Please remove the false provenance claim so the reference does not assert source content that is not present.

Note this list is nearly identical to `index.ts`'s own top-level JSDoc module comment (both files carry the same doc block), but `index.ts` itself re-exports far more (all of `environments.ts`, `insomnia.ts`, `test.ts`, `execution.ts`, etc.) in addition to wrapping this file as the `Collection` namespace.

.claude/skills/fix-scripting-feature/references/objects/cookies.md:22

• toString() does not append ; Session from the session option. The implementation checks whether tough-cookie's extensions contain lowercase 'session', while Cookie.parse() extracts/removes the capitalized Session flag and the constructor passes the boolean separately. The existing test constructs session: true and expects no Session marker, so the current description is misleading.

- `toString(): string` — tough-cookie's own `toString()` plus `; HostOnly`, `; Session`, and `; key=value` segments appended for any extensions/inso flags present.

.claude/skills/fix-scripting-feature/references/objects/folders.md:42

• Although TypeScript declares parentFolders as private, it is assigned as an ordinary own property and the InsomniaObject proxy forwards unknown properties with Reflect.get. Scripts can therefore use insomnia.parentFolders (the editor even provides snippets for it); this statement incorrectly hides a script-facing API.

There is no `insomnia.parentFolders` / `insomnia.folders` public property — `parentFolders` is a private field on `InsomniaObject`.

.claude/skills/fix-scripting-feature/references/objects/folders.md:53

• index.ts uses export * from './folders', so it re-exports ParentFolders as well as Folder. The current related-file note says the opposite and can mislead consumers trying to import the container type.

- `index.ts` — re-exports `Folder` (but not `ParentFolders`) at the top level; `collection.ts` also re-exports `Folder`.

.claude/skills/fix-scripting-feature/references/objects/headers.md:36

• HeaderList.add() accepts/stores the item but does not convert a plain object into a Header. The documented pm.request.headers.add({key, value}) therefore leaves a raw object in the list, and the later request merge calls .toJSON() and fails. Use the Request.addHeader convenience method for a plain object, or construct/import a Header for direct list insertion.

`pm.request.headers` and `pm.response.headers` are `HeaderList<Header>` instances. Beyond the methods above, all generic `PropertyList` methods are available: `add`/`append`, `all()`, `assimilate()`, `clear()`, `count()`, `each()`, `filter()`, `find()`, `get(key)` / `one(key)` (keyed by `key` since `Header._index = 'key'`), `has()`, `idx()`, `indexOf()`, `insert()`/`insertAfter()`, `map()`, `populate()`, `prepend()`, `reduce()`, `remove()`, `repopulate()`, `toString()`, `upsert()`. Typical script usage: `pm.request.headers.add({key, value})`, `pm.request.headers.get('Content-Type')`, `pm.response.headers.has(...)`, `pm.request.headers.upsert(new Header({...}))`.

.claude/skills/fix-scripting-feature/references/objects/properties.md:82

• pm.request.url.query is constructed as new PropertyList(QueryParam, ...); it is not a UrlMatchPatternList. Please correct this mapping so query-parameter debugging leads to urls.ts/QueryParam.

- `pm.request.url.query` → `UrlMatchPatternList`/similar list types.

.claude/skills/fix-scripting-feature/references/objects/proxy-configs.md:23

• For an active proxy, protocol comes from URL.protocol and includes the trailing colon (http:/https:); getProxyUrl() then appends //. The example without a colon can produce an invalid URL when consumers construct a ProxyConfig themselves. Please document the colon requirement and the disabled default separately.

- `protocol: string` — e.g. `"http"`/`"https"`.

.claude/skills/fix-scripting-feature/references/objects/proxy-configs.md:46

• The example passes plain objects into ProxyConfigList, but PropertyList stores populate unchanged; it does not construct ProxyConfig instances. Calling resolve() or toObject() then invokes .test()/.toJSON() on those plain objects and fails. The example should construct each ProxyConfig (and provide its required fields).

- `ProxyConfigList` and `ProxyConfig` are also exported from the `insomnia-collection` module (via `collection.ts`) so scripts can `require('insomnia-collection')` and construct their own lists directly, e.g.: `new ProxyConfigList(undefined, [{match: 'https://example.com/*', host: 'proxy.com', port: 8080, tunnel: true}, ...])` (per the inline example comment in the source). There is no evidence in the SDK object graph that `pm.request` itself ever holds a `ProxyConfigList` — only a single `ProxyConfig`.

.claude/skills/fix-scripting-feature/references/objects/request-info.md:44

• insomnia.info.iteration is not reliably 1-based in the current collection-runner path: inso calls sendRequest(req._id, i) with zero-based i, and RequestInfo applies options.iteration || 1, so iterations 0 and 1 both surface as 1. The reference should describe this actual behavior rather than promise a correct 1-based counter.

- `insomnia.info.iteration` — current collection-runner iteration number (1-based).

.claude/skills/fix-scripting-feature/references/objects/request.md:81

• This repeats the incorrect conflict rule: the implementation checks for a non-empty PFX first and returns it even if cert/key are set too. Please describe the precedence and the actual invalid-input case instead.

- `mergeClientCertificates` throws if a script sets both `cert`+`key` and `pfx` on `pm.request.certificate` at the same time — Insomnia only supports one or the other.

.claude/skills/fix-scripting-feature/references/objects/request.md:58

• The precedence in this description is backwards. mergeRequestBody first derives a MIME type from the script body mode, then unconditionally replaces it when originalReqBody.mimeType is truthy, so a stale original MIME type can override a script mode change.

- `mergeRequestBody(updatedReqBody: RequestBody | undefined, originalReqBody: InsomniaRequestBody): InsomniaRequestBody` — infers `mimeType` from `updatedReqBody.mode` (falls back to `originalReqBody.mimeType` if set); **throws** on an unknown `mode`; wraps any other failure as `Error("failed to update body: ...")`.

.claude/skills/fix-scripting-feature/references/objects/send-request.md:16

• The code block presents cb as required, while the implementation checks for a falsy callback and the script-facing section documents pm.sendRequest(url) without one. This leaves the TypeScript contract inconsistent with the documented runtime form; either make the callback optional in both public declarations or explicitly label callback-free use as runtime-only.

export async function sendRequest(
  request: string | Request | RequestOptions,
  cb: (error?: string, response?: Response) => void,
  settings: Settings,
): Promise<Response | void>

.claude/skills/fix-scripting-feature/references/objects/test.md:21

• test is declared async, so its caller receives the outer async function's promise rather than the exact testPromise object returned by wrapFn(). The settlement behavior is as described, but the promise identity is not; please avoid claiming that test() returns the same promise.

- Immediately invokes `wrapFn()`, registers the resulting promise with `startTestObserver`, and returns that same promise (`testPromise`) — i.e. `test()` itself resolves once the wrapped test body (pass or fail) has finished running.

.claude/skills/fix-scripting-feature/references/objects/urls.md:62

• The test() implementation does not compare the input URL's path: it passes this.pattern to getPath, and testPath then compares that same pattern-derived path with itself. Thus the input path does not affect the result, contrary to this description.

- `test(urlStr: string): boolean` — true only if protocol, host, path, and port all match.

.claude/skills/fix-scripting-feature/references/objects/urls.md:54

• <all_urls> is only special-cased by getProtocols(). test() still derives host/path from the literal <all_urls> string, so it generally does not match ordinary URLs. Please qualify the support claim here.

Implements [Chrome extension match patterns](https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns) (`scheme://host/path`, wildcards, `<all_urls>`); comment notes it doesn't support top-level-domain wildcards, and that URLs can't start with `-` (unenforced).

.claude/skills/fix-scripting-feature/references/objects/variables.md:6

• The example is misleading: the SDK's VariableList is used for authentication option lists (RequestAuth/Request.authorizeUsing), not request path parameters (which use RequestPathParameter[]). Pointing readers to request path parameters sends them to the wrong model when debugging.

This file defines the low-level key/value model — `Variable` (a single named, typed value) and `VariableList` (an ordered, keyed collection of `Variable`s) — built on top of `Property`/`PropertyList` from `properties.ts`. Unlike `Environment` (a `Map`-backed flat store used for `pm.environment`/`pm.globals`), `Variable`/`VariableList` is the object-per-entry model used elsewhere in the SDK wherever a Postman-compatible "list of variable-shaped items" is needed (e.g. request path parameters); it is not the type behind `insomnia.environment` or `insomnia.variables`.

.claude/skills/fix-scripting-feature/references/objects/variables.md:27

• For an omitted def, the constructor assigns this.name = '', not undefined (variables.ts:58-63). The distinction is observable through serialization and when debugging a newly-created Variable; please correct this documented default.

Calls `super()` (no args passed to `Property`'s constructor, so `Property`'s own `id`/`name`/`disabled` defaults are set first, then overwritten below). When `def` is provided: `id = def.id || ''`, `key = def.key`, `name = def.name`, `value = def.value`, `type = def.type || 'Variable'`, `disabled = def.disabled`. When `def` is omitted: `id = ''`, `key = ''`, `name = undefined`, `value = ''`, `type = 'Variable'`, `disabled = false`.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.