@psnext/slingcli 2.4.20260520-2 → 2.4.20260520-4

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/docs/docs/best-practices/undici-vs-builtin-fetch.md

@@ -0,0 +1,224 @@
+# Undici Module vs. Node.js Built-in Fetch
+
+Node.js has shipped a built-in `fetch()` implementation powered by undici since
+Node.js v18. This guide explains the relationship between the `undici` npm
+package and the built-in `fetch`, and when you should install one versus relying
+on the other.
+
+## Background
+
+The `fetch()`, `Request`, `Response`, `Headers`, and `FormData` globals in
+Node.js v18+ are provided by a version of undici that is bundled into Node.js
+itself. You can check which version is bundled with:
+
+```js
+console.log(process.versions.undici); // e.g., "7.5.0"
+```
+
+When you install undici from npm, you get the full library with all of its
+additional APIs, and potentially a newer release than what your Node.js version
+bundles.
+
+## Keep `fetch` and `FormData` from the same implementation
+
+When you send a `FormData` body, keep `fetch` and `FormData` together from the
+same implementation.
+
+Use one of these patterns:
+
+### Built-in globals
+
+```js
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+### `undici` module imports
+
+```js
+import { fetch, FormData } from 'undici'
+
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+### `undici.install()` globals
+
+If you want the installed `undici` package to provide the globals, call
+[`install()`](/docs/api/GlobalInstallation.md):
+
+```js
+import { install } from 'undici'
+
+install()
+
+const body = new FormData()
+body.set('name', 'some')
+body.set('someOtherProperty', '8000')
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
+`FormData` implementations with undici's versions, and also installs undici's
+`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
+globals.
+
+Avoid mixing implementations in the same request, for example:
+
+```js
+import { fetch } from 'undici'
+
+const body = new FormData()
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+```js
+import { FormData } from 'undici'
+
+const body = new FormData()
+
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+Those combinations may behave differently across Node.js and undici versions.
+Using matching pairs keeps multipart handling predictable.
+
+## When you do NOT need to install undici
+
+If all of the following are true, you can rely on the built-in globals and skip
+adding undici to your dependencies:
+
+- You only need the standard Fetch API (`fetch`, `Request`, `Response`,
+  `Headers`, `FormData`).
+- You are running Node.js v18 or later.
+- You do not depend on features or bug fixes introduced in a version of undici
+  newer than the one bundled with your Node.js release.
+- You want zero additional runtime dependencies.
+- You want cross-platform interoperability with browsers and other runtimes
+  (Deno, Bun, Cloudflare Workers, etc.) using the same Fetch API surface.
+
+This is common in applications that make straightforward HTTP requests or in
+libraries that target multiple JavaScript runtimes.
+
+## When you SHOULD install undici
+
+Install undici from npm when you need capabilities beyond the standard Fetch API:
+
+### Advanced HTTP APIs
+
+undici exposes `request`, `stream`, `pipeline`, and `connect` methods that
+provide lower-level control and significantly better performance than `fetch`:
+
+```js
+import { request } from 'undici';
+
+const { statusCode, headers, body } = await request('https://example.com');
+const data = await body.json();
+```
+
+### Connection pooling and dispatchers
+
+`Client`, `Pool`, `BalancedPool`, `Agent`, and their configuration options
+let you manage connection lifecycle, keep-alive behavior, pipelining depth,
+and concurrency limits:
+
+```js
+import { Pool } from 'undici';
+
+const pool = new Pool('https://example.com', { connections: 10 });
+const { body } = await pool.request({ path: '/', method: 'GET' });
+```
+
+### Proxy support
+
+`ProxyAgent` and `EnvHttpProxyAgent` handle HTTP(S) proxying. Note that
+Node.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy
+configuration for the built-in `fetch` via the `--use-env-proxy` flag (or
+`NODE_USE_ENV_PROXY=1`). However, undici's `ProxyAgent` still provides
+programmatic control through the dispatcher API:
+
+```js
+import { ProxyAgent, fetch } from 'undici';
+
+const proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');
+const response = await fetch('https://example.com', { dispatcher: proxyAgent });
+```
+
+### Testing and mocking
+
+`MockAgent`, `MockClient`, and `MockPool` let you intercept and mock HTTP
+requests without patching globals or depending on external libraries:
+
+```js
+import { MockAgent, setGlobalDispatcher, fetch } from 'undici';
+
+const mockAgent = new MockAgent();
+setGlobalDispatcher(mockAgent);
+
+const pool = mockAgent.get('https://example.com');
+pool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });
+```
+
+### Interceptors and middleware
+
+Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you
+fine-grained control over how requests are processed.
+
+### Newer version than what Node.js bundles
+
+The npm package often includes features, performance improvements, and bug fixes
+that have not yet landed in a Node.js release. If you need a specific fix or
+feature, you can install a newer version directly.
+
+## Version compatibility
+
+| Node.js version | Bundled undici version | Notes |
+|---|---|---|
+| v18.x | ~5.x | `fetch` is experimental (behind `--experimental-fetch` in early v18) |
+| v20.x | ~6.x | `fetch` is stable |
+| v22.x | ~6.x / ~7.x | `fetch` is stable |
+| v24.x | ~7.x | `fetch` is stable; env-proxy support via `--use-env-proxy` |
+
+You can always check the exact bundled version at runtime with
+`process.versions.undici`.
+
+Installing undici from npm does not replace the built-in globals. If you want
+your installed version to replace the global `fetch` and related classes, use
+[`install()`](/docs/api/GlobalInstallation.md). Otherwise, import `fetch`
+directly from `'undici'`:
+
+```js
+import { fetch } from 'undici' // uses your installed version, not the built-in
+```
+
+## Further reading
+
+- [API Reference: Fetch](/docs/api/Fetch.md)
+- [API Reference: Client](/docs/api/Client.md)
+- [API Reference: Pool](/docs/api/Pool.md)
+- [API Reference: ProxyAgent](/docs/api/ProxyAgent.md)
+- [API Reference: MockAgent](/docs/api/MockAgent.md)
+- [API Reference: Global Installation](/docs/api/GlobalInstallation.md)

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/docs/docs/best-practices/writing-tests.md

@@ -0,0 +1,63 @@
+# Writing tests
+
+Undici is tuned for a production use case and its default will keep
+a socket open for a few seconds after an HTTP request is completed to
+remove the overhead of opening up a new socket. These settings that makes
+Undici shine in production are not a good fit for using Undici in automated
+tests, as it will result in longer execution times.
+
+The following are good defaults that will keep the socket open for only 10ms:
+
+```js
+import { request, setGlobalDispatcher, Agent } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 10, // milliseconds
+  keepAliveMaxTimeout: 10 // milliseconds
+})
+
+setGlobalDispatcher(agent)
+```
+
+## Guarding against unexpected disconnects
+
+Undici's `Client` automatically reconnects after a socket error. This means
+a test can silently disconnect, reconnect, and still pass. Unfortunately, 
+this could mask bugs like unexpected parser errors or protocol violations.
+To catch these silent reconnections, add a disconnect guard after creating 
+a `Client`:
+
+```js
+const { Client } = require('undici')
+const { test, after } = require('node:test')
+const { tspl } = require('@matteo.collina/tspl')
+
+test('example with disconnect guard', async (t) => {
+  t = tspl(t, { plan: 1 })
+
+  const client = new Client('http://localhost:3000')
+  after(() => client.close())
+
+  client.on('disconnect', () => {
+    if (!client.closed && !client.destroyed) {
+      t.fail('unexpected disconnect')
+    }
+  })
+
+  // ... test logic ...
+})
+```
+
+`client.close()` and `client.destroy()` both emit `'disconnect'` events, but
+those are expected. The guard only fails when a disconnect happens during the
+active test (i.e., `!client.closed && !client.destroyed` is true).
+
+Skip the guard for tests where a disconnect is expected behavior, such as:
+
+- Signal aborts (`signal.emit('abort')`, `ac.abort()`)
+- Server-side destruction (`res.destroy()`, `req.socket.destroy()`)
+- Client-side body destruction mid-stream (`data.body.destroy()`)
+- Timeout errors (`HeadersTimeoutError`, `BodyTimeoutError`)
+- Successful upgrades (the socket is detached from the `Client`)
+- Retry/reconnect tests where the disconnect triggers the retry
+- HTTP parser errors from malformed responses (`HTTPParserError`)

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/index-fetch.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
+const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
+const fetchImpl = require('./lib/web/fetch').fetch
+
+// Capture __filename at module load time for stack trace augmentation.
+// This may be undefined when bundled in environments like Node.js internals.
+const currentFilename = typeof __filename !== 'undefined' ? __filename : undefined
+
+function appendFetchStackTrace (err, filename) {
+  if (!err || typeof err !== 'object') {
+    return
+  }
+
+  const stack = typeof err.stack === 'string' ? err.stack : ''
+  const normalizedFilename = filename.replace(/\\/g, '/')
+
+  if (stack && (stack.includes(filename) || stack.includes(normalizedFilename))) {
+    return
+  }
+
+  const capture = {}
+  Error.captureStackTrace(capture, appendFetchStackTrace)
+
+  if (!capture.stack) {
+    return
+  }
+
+  const captureLines = capture.stack.split('\n').slice(1).join('\n')
+
+  err.stack = stack ? `${stack}\n${captureLines}` : capture.stack
+}
+
+module.exports.fetch = function fetch (init, options = undefined) {
+  return fetchImpl(init, options).catch(err => {
+    if (currentFilename) {
+      appendFetchStackTrace(err, currentFilename)
+    } else if (err && typeof err === 'object') {
+      Error.captureStackTrace(err, module.exports.fetch)
+    }
+    throw err
+  })
+}
+module.exports.FormData = require('./lib/web/fetch/formdata').FormData
+module.exports.Headers = require('./lib/web/fetch/headers').Headers
+module.exports.Response = require('./lib/web/fetch/response').Response
+module.exports.Request = require('./lib/web/fetch/request').Request
+
+const { CloseEvent, ErrorEvent, MessageEvent, createFastMessageEvent } = require('./lib/web/websocket/events')
+module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+module.exports.CloseEvent = CloseEvent
+module.exports.ErrorEvent = ErrorEvent
+module.exports.MessageEvent = MessageEvent
+module.exports.createFastMessageEvent = createFastMessageEvent
+
+module.exports.EventSource = require('./lib/web/eventsource/eventsource').EventSource
+
+const api = require('./lib/api')
+const Dispatcher = require('./lib/dispatcher/dispatcher')
+Object.assign(Dispatcher.prototype, api)
+// Expose the fetch implementation to be enabled in Node.js core via a flag
+module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
+module.exports.getGlobalDispatcher = getGlobalDispatcher
+module.exports.setGlobalDispatcher = setGlobalDispatcher

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/index.js

@@ -0,0 +1,236 @@
+'use strict'
+
+const Client = require('./lib/dispatcher/client')
+const Dispatcher = require('./lib/dispatcher/dispatcher')
+const Pool = require('./lib/dispatcher/pool')
+const BalancedPool = require('./lib/dispatcher/balanced-pool')
+const RoundRobinPool = require('./lib/dispatcher/round-robin-pool')
+const Agent = require('./lib/dispatcher/agent')
+const Dispatcher1Wrapper = require('./lib/dispatcher/dispatcher1-wrapper')
+const ProxyAgent = require('./lib/dispatcher/proxy-agent')
+const Socks5ProxyAgent = require('./lib/dispatcher/socks5-proxy-agent')
+const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
+const RetryAgent = require('./lib/dispatcher/retry-agent')
+const H2CClient = require('./lib/dispatcher/h2c-client')
+const errors = require('./lib/core/errors')
+const util = require('./lib/core/util')
+const { InvalidArgumentError } = errors
+const api = require('./lib/api')
+const buildConnector = require('./lib/core/connect')
+const MockClient = require('./lib/mock/mock-client')
+const { MockCallHistory, MockCallHistoryLog } = require('./lib/mock/mock-call-history')
+const MockAgent = require('./lib/mock/mock-agent')
+const MockPool = require('./lib/mock/mock-pool')
+const SnapshotAgent = require('./lib/mock/snapshot-agent')
+const mockErrors = require('./lib/mock/mock-errors')
+const RetryHandler = require('./lib/handler/retry-handler')
+const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
+const DecoratorHandler = require('./lib/handler/decorator-handler')
+const RedirectHandler = require('./lib/handler/redirect-handler')
+
+Object.assign(Dispatcher.prototype, api)
+
+module.exports.Dispatcher = Dispatcher
+module.exports.Client = Client
+module.exports.Pool = Pool
+module.exports.BalancedPool = BalancedPool
+module.exports.RoundRobinPool = RoundRobinPool
+module.exports.Agent = Agent
+module.exports.Dispatcher1Wrapper = Dispatcher1Wrapper
+module.exports.ProxyAgent = ProxyAgent
+module.exports.Socks5ProxyAgent = Socks5ProxyAgent
+module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
+module.exports.RetryAgent = RetryAgent
+module.exports.H2CClient = H2CClient
+module.exports.RetryHandler = RetryHandler
+
+module.exports.DecoratorHandler = DecoratorHandler
+module.exports.RedirectHandler = RedirectHandler
+module.exports.interceptors = {
+  redirect: require('./lib/interceptor/redirect'),
+  responseError: require('./lib/interceptor/response-error'),
+  retry: require('./lib/interceptor/retry'),
+  dump: require('./lib/interceptor/dump'),
+  dns: require('./lib/interceptor/dns'),
+  cache: require('./lib/interceptor/cache'),
+  decompress: require('./lib/interceptor/decompress'),
+  deduplicate: require('./lib/interceptor/deduplicate')
+}
+
+module.exports.cacheStores = {
+  MemoryCacheStore: require('./lib/cache/memory-cache-store')
+}
+
+const SqliteCacheStore = require('./lib/cache/sqlite-cache-store')
+module.exports.cacheStores.SqliteCacheStore = SqliteCacheStore
+
+module.exports.buildConnector = buildConnector
+module.exports.errors = errors
+module.exports.util = {
+  parseHeaders: util.parseHeaders,
+  headerNameToString: util.headerNameToString
+}
+
+function makeDispatcher (fn) {
+  return (url, opts, handler) => {
+    if (typeof opts === 'function') {
+      handler = opts
+      opts = null
+    }
+
+    if (!url || (typeof url !== 'string' && typeof url !== 'object' && !(url instanceof URL))) {
+      throw new InvalidArgumentError('invalid url')
+    }
+
+    if (opts != null && typeof opts !== 'object') {
+      throw new InvalidArgumentError('invalid opts')
+    }
+
+    if (opts && opts.path != null) {
+      if (typeof opts.path !== 'string') {
+        throw new InvalidArgumentError('invalid opts.path')
+      }
+
+      let path = opts.path
+      if (!opts.path.startsWith('/')) {
+        path = `/${path}`
+      }
+
+      url = new URL(util.parseOrigin(url).origin + path)
+    } else {
+      if (!opts) {
+        opts = typeof url === 'object' ? url : {}
+      }
+
+      url = util.parseURL(url)
+    }
+
+    const { agent, dispatcher = getGlobalDispatcher(), ...restOpts } = opts
+
+    if (agent) {
+      throw new InvalidArgumentError('unsupported opts.agent. Did you mean opts.client?')
+    }
+
+    return fn.call(dispatcher, {
+      ...restOpts,
+      origin: url.origin,
+      path: url.search ? `${url.pathname}${url.search}` : url.pathname,
+      method: opts.method || (opts.body ? 'PUT' : 'GET')
+    }, handler)
+  }
+}
+
+module.exports.setGlobalDispatcher = setGlobalDispatcher
+module.exports.getGlobalDispatcher = getGlobalDispatcher
+
+const fetchImpl = require('./lib/web/fetch').fetch
+
+// Capture __filename at module load time for stack trace augmentation.
+// This may be undefined when bundled in environments like Node.js internals.
+const currentFilename = typeof __filename !== 'undefined' ? __filename : undefined
+
+function appendFetchStackTrace (err, filename) {
+  if (!err || typeof err !== 'object') {
+    return
+  }
+
+  const stack = typeof err.stack === 'string' ? err.stack : ''
+  const normalizedFilename = filename.replace(/\\/g, '/')
+
+  if (stack && (stack.includes(filename) || stack.includes(normalizedFilename))) {
+    return
+  }
+
+  const capture = {}
+  Error.captureStackTrace(capture, appendFetchStackTrace)
+
+  if (!capture.stack) {
+    return
+  }
+
+  const captureLines = capture.stack.split('\n').slice(1).join('\n')
+
+  err.stack = stack ? `${stack}\n${captureLines}` : capture.stack
+}
+
+module.exports.fetch = function fetch (init, options = undefined) {
+  return fetchImpl(init, options).catch(err => {
+    if (currentFilename) {
+      appendFetchStackTrace(err, currentFilename)
+    } else if (err && typeof err === 'object') {
+      Error.captureStackTrace(err, module.exports.fetch)
+    }
+    throw err
+  })
+}
+module.exports.Headers = require('./lib/web/fetch/headers').Headers
+module.exports.Response = require('./lib/web/fetch/response').Response
+module.exports.Request = require('./lib/web/fetch/request').Request
+module.exports.FormData = require('./lib/web/fetch/formdata').FormData
+
+const { setGlobalOrigin, getGlobalOrigin } = require('./lib/web/fetch/global')
+
+module.exports.setGlobalOrigin = setGlobalOrigin
+module.exports.getGlobalOrigin = getGlobalOrigin
+
+const { CacheStorage } = require('./lib/web/cache/cachestorage')
+const { kConstruct } = require('./lib/core/symbols')
+
+module.exports.caches = new CacheStorage(kConstruct)
+
+const { deleteCookie, getCookies, getSetCookies, setCookie, parseCookie } = require('./lib/web/cookies')
+
+module.exports.deleteCookie = deleteCookie
+module.exports.getCookies = getCookies
+module.exports.getSetCookies = getSetCookies
+module.exports.setCookie = setCookie
+module.exports.parseCookie = parseCookie
+
+const { parseMIMEType, serializeAMimeType } = require('./lib/web/fetch/data-url')
+
+module.exports.parseMIMEType = parseMIMEType
+module.exports.serializeAMimeType = serializeAMimeType
+
+const { CloseEvent, ErrorEvent, MessageEvent } = require('./lib/web/websocket/events')
+const { WebSocket, ping } = require('./lib/web/websocket/websocket')
+module.exports.WebSocket = WebSocket
+module.exports.CloseEvent = CloseEvent
+module.exports.ErrorEvent = ErrorEvent
+module.exports.MessageEvent = MessageEvent
+module.exports.ping = ping
+
+module.exports.WebSocketStream = require('./lib/web/websocket/stream/websocketstream').WebSocketStream
+module.exports.WebSocketError = require('./lib/web/websocket/stream/websocketerror').WebSocketError
+
+module.exports.request = makeDispatcher(api.request)
+module.exports.stream = makeDispatcher(api.stream)
+module.exports.pipeline = makeDispatcher(api.pipeline)
+module.exports.connect = makeDispatcher(api.connect)
+module.exports.upgrade = makeDispatcher(api.upgrade)
+
+module.exports.MockClient = MockClient
+module.exports.MockCallHistory = MockCallHistory
+module.exports.MockCallHistoryLog = MockCallHistoryLog
+module.exports.MockPool = MockPool
+module.exports.MockAgent = MockAgent
+module.exports.SnapshotAgent = SnapshotAgent
+module.exports.mockErrors = mockErrors
+
+const { EventSource } = require('./lib/web/eventsource/eventsource')
+
+module.exports.EventSource = EventSource
+
+function install () {
+  globalThis.fetch = module.exports.fetch
+  globalThis.Headers = module.exports.Headers
+  globalThis.Response = module.exports.Response
+  globalThis.Request = module.exports.Request
+  globalThis.FormData = module.exports.FormData
+  globalThis.WebSocket = module.exports.WebSocket
+  globalThis.CloseEvent = module.exports.CloseEvent
+  globalThis.ErrorEvent = module.exports.ErrorEvent
+  globalThis.MessageEvent = module.exports.MessageEvent
+  globalThis.EventSource = module.exports.EventSource
+}
+
+module.exports.install = install

package/node_modules/@earendil-works/pi-coding-agent/node_modules/undici/lib/api/abort-signal.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const { addAbortListener } = require('../core/util')
+const { RequestAbortedError } = require('../core/errors')
+
+const kListener = Symbol('kListener')
+const kSignal = Symbol('kSignal')
+
+function abort (self) {
+  if (self.abort) {
+    self.abort(self[kSignal]?.reason)
+  } else {
+    self.reason = self[kSignal]?.reason ?? new RequestAbortedError()
+  }
+  removeSignal(self)
+}
+
+function addSignal (self, signal) {
+  self.reason = null
+
+  self[kSignal] = null
+  self[kListener] = null
+
+  if (!signal) {
+    return
+  }
+
+  if (signal.aborted) {
+    abort(self)
+    return
+  }
+
+  self[kSignal] = signal
+  self[kListener] = () => {
+    abort(self)
+  }
+
+  addAbortListener(self[kSignal], self[kListener])
+}
+
+function removeSignal (self) {
+  if (!self[kSignal]) {
+    return
+  }
+
+  if ('removeEventListener' in self[kSignal]) {
+    self[kSignal].removeEventListener('abort', self[kListener])
+  } else {
+    self[kSignal].removeListener('abort', self[kListener])
+  }
+
+  self[kSignal] = null
+  self[kListener] = null
+}
+
+module.exports = {
+  addSignal,
+  removeSignal
+}