@aidra/pmx-io 0.0.0-stage → 9.13.0

package/lib/transport/ws.js

@@ -0,0 +1,511 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// HTTP/1.1 requests and an RFC 6455 WebSocket client over net/tls, for the standalone transport
+// (80 NIO-264, PYI-155 conformance). No dependency and no use of http/https/fetch, so the
+// library's own requests are never seen by its outbound instrumentation (NIO-222) and loading
+// it costs nothing at start-up. Every socket is unref'd: the transport never keeps the app alive.
+//
+//  * handshake: 101 with `Upgrade: websocket`, `Connection` containing `upgrade`, the correct
+//    Sec-WebSocket-Accept, and no extension or subprotocol the client did not ask for;
+//  * every client frame masked with a fresh key; one text frame per message;
+//  * incoming fragmented messages reassembled; text validated as UTF-8 (else close 1007);
+//    a masked server frame, a reserved bit, an unknown opcode, or a control frame longer than
+//    125 bytes or fragmented closes with 1002; messages over 16 MiB close with 1009;
+//  * pings answered with the same payload; close handshake with a 2 s timeout;
+//  * proxy (opt-in): CONNECT tunnel with Basic auth for https and for the WebSocket; plain
+//    http requests are sent to the proxy in absolute form. TLS to prodman always uses
+//    SNI = prodman's host and the runtime's CA store (NODE_EXTRA_CA_CERTS applies).
+
+const net = require('net')
+const crypto = require('crypto')
+const { EventEmitter } = require('events')
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+const MAX_MESSAGE = 16 * 1024 * 1024
+const CLOSE_TIMEOUT = 2000
+
+function parseUrl (u) {
+  const url = u instanceof URL ? u : new URL(u)
+  const secure = url.protocol === 'https:' || url.protocol === 'wss:'
+  return {
+    url,
+    secure,
+    host: url.hostname.replace(/^\[|\]$/g, ''),
+    port: Number(url.port) || (secure ? 443 : 80),
+    hostHeader: url.host,
+    path: (url.pathname || '/') + (url.search || '')
+  }
+}
+
+function proxyAuth (proxy) {
+  if (!proxy || !proxy.username) return null
+  const user = decodeURIComponent(proxy.username)
+  const pass = decodeURIComponent(proxy.password || '')
+  return 'Basic ' + Buffer.from(user + ':' + pass).toString('base64')
+}
+
+function parseHead (buf) {
+  const end = buf.indexOf('\r\n\r\n')
+  if (end === -1) return null
+  const head = buf.slice(0, end).toString('latin1')
+  const [statusLine, ...lines] = head.split('\r\n')
+  const status = Number(statusLine.split(' ')[1])
+  const headers = {}
+  for (const l of lines) {
+    const i = l.indexOf(':')
+    if (i > 0) {
+      const k = l.slice(0, i).trim().toLowerCase()
+      const v = l.slice(i + 1).trim()
+      headers[k] = headers[k] !== undefined ? headers[k] + ', ' + v : v
+    }
+  }
+  return { status, headers, rest: buf.slice(end + 4) }
+}
+
+function withTimeout (sock, ms, onTimeout) {
+  if (!ms) return () => {}
+  const t = setTimeout(() => {
+    onTimeout()
+    sock.destroy(new Error('timeout'))
+  }, ms)
+  if (t.unref) t.unref()
+  return () => clearTimeout(t)
+}
+
+/**
+ * A TCP (or TLS) socket to `target` ({host, port, secure}), through `proxy` (a URL) if given.
+ * `opts.timeout` (ms) bounds the whole set-up — TCP connect, proxy CONNECT and TLS handshake —
+ * as pmx-io's deadline does (PYI-155): a peer that accepts and then stays silent can never
+ * leave the transport waiting for ever.
+ */
+function openSocket (target, opts) {
+  opts = opts || {}
+  const proxy = opts.proxy ? (opts.proxy instanceof URL ? opts.proxy : new URL(opts.proxy)) : null
+  return new Promise((resolve, reject) => {
+    let done = false
+    let current = null
+    let timer = null
+    const fail = (err) => {
+      if (done) return
+      done = true
+      if (timer) clearTimeout(timer)
+      if (current) {
+        try {
+          current.destroy()
+        } catch (_) {}
+      }
+      reject(err)
+    }
+    const succeed = (s) => {
+      if (done) return
+      done = true
+      if (timer) clearTimeout(timer)
+      resolve(s)
+    }
+    if (opts.timeout > 0) {
+      timer = setTimeout(() => fail(new Error('connect timeout')), opts.timeout)
+      if (timer.unref) timer.unref()
+    }
+    const secureUp = (raw) => {
+      if (!target.secure) {
+        succeed(raw)
+        return
+      }
+      const tls = require('tls')
+      const s = tls.connect({ socket: raw, servername: net.isIP(target.host) ? undefined : target.host, host: target.host })
+      current = s
+      if (s.unref) s.unref()
+      s.once('secureConnect', () => succeed(s))
+      s.on('error', fail)
+    }
+    if (!proxy) {
+      const s = net.connect({ host: target.host, port: target.port })
+      current = s
+      if (s.unref) s.unref()
+      s.setNoDelay(true)
+      s.on('error', fail)
+      s.once('connect', () => secureUp(s))
+      return
+    }
+    const pPort = Number(proxy.port) || 80
+    const s = net.connect({ host: proxy.hostname.replace(/^\[|\]$/g, ''), port: pPort })
+    current = s
+    if (s.unref) s.unref()
+    s.setNoDelay(true)
+    s.on('error', fail)
+    s.once('close', () => fail(new Error('proxy closed the connection')))
+    s.once('connect', () => {
+      const authority = (net.isIPv6(target.host) ? `[${target.host}]` : target.host) + ':' + target.port
+      const lines = [`CONNECT ${authority} HTTP/1.1`, `Host: ${authority}`]
+      const auth = proxyAuth(proxy)
+      if (auth) lines.push(`Proxy-Authorization: ${auth}`)
+      s.write(lines.join('\r\n') + '\r\n\r\n')
+      let buf = Buffer.alloc(0)
+      const onData = (chunk) => {
+        buf = Buffer.concat([buf, chunk])
+        const h = parseHead(buf)
+        if (!h) {
+          if (buf.length > 65536) fail(new Error('proxy response too large'))
+          return
+        }
+        s.removeListener('data', onData)
+        if (h.status !== 200) {
+          fail(new Error(`proxy CONNECT failed: ${h.status}`))
+          return
+        }
+        if (h.rest.length) s.unshift(h.rest)
+        secureUp(s)
+      }
+      s.on('data', onData)
+    })
+  })
+}
+
+function decodeChunked (buf) {
+  const parts = []
+  let i = 0
+  for (;;) {
+    const nl = buf.indexOf('\r\n', i)
+    if (nl === -1) return null
+    const size = parseInt(buf.slice(i, nl).toString('latin1').split(';')[0].trim(), 16)
+    if (!Number.isFinite(size)) return null
+    if (size === 0) return Buffer.concat(parts)
+    if (buf.length < nl + 2 + size + 2) return null
+    parts.push(buf.slice(nl + 2, nl + 2 + size))
+    i = nl + 2 + size + 2
+  }
+}
+
+/**
+ * A minimal HTTP/1.1 request (Connection: close). Resolves { status, headers, body }.
+ * @param {{timeout?: number, proxy?: string|URL}} [opts]
+ */
+function httpRequest (method, url, body, headers, opts) {
+  opts = opts || {}
+  const t = parseUrl(url)
+  const proxy = opts.proxy ? (opts.proxy instanceof URL ? opts.proxy : new URL(opts.proxy)) : null
+  const viaAbsolute = proxy && !t.secure
+  const sockTarget = viaAbsolute ? { host: proxy.hostname.replace(/^\[|\]$/g, ''), port: Number(proxy.port) || 80, secure: false } : t
+  const payload = body === null || body === undefined ? null : Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf8')
+  const deadline = opts.timeout ? Date.now() + opts.timeout : 0
+  return openSocket(sockTarget, { proxy: viaAbsolute ? null : proxy, timeout: opts.timeout }).then((sock) => new Promise((resolve, reject) => {
+    let settled = false
+    const finish = (err, res) => {
+      if (settled) return
+      settled = true
+      clear()
+      try {
+        sock.destroy()
+      } catch (_) {}
+      if (err) reject(err)
+      else resolve(res)
+    }
+    const clear = withTimeout(sock, deadline ? Math.max(1, deadline - Date.now()) : 0, () => finish(new Error('timeout')))
+    const lines = [`${method} ${viaAbsolute ? t.url.href : t.path} HTTP/1.1`, `Host: ${t.hostHeader}`, 'Connection: close']
+    if (viaAbsolute) {
+      const auth = proxyAuth(proxy)
+      if (auth) lines.push(`Proxy-Authorization: ${auth}`)
+    }
+    for (const k of Object.keys(headers || {})) lines.push(`${k}: ${headers[k]}`)
+    if (payload) lines.push(`Content-Length: ${payload.length}`)
+    sock.write(lines.join('\r\n') + '\r\n\r\n')
+    if (payload) sock.write(payload)
+    const chunks = []
+    let total = 0
+    const tryParse = (final) => {
+      const buf = Buffer.concat(chunks)
+      const h = parseHead(buf)
+      if (!h) {
+        if (final) finish(new Error('incomplete response'))
+        return
+      }
+      const len = h.headers['content-length']
+      if (len !== undefined) {
+        const n = Number(len)
+        if (h.rest.length >= n) return finish(null, { status: h.status, headers: h.headers, body: h.rest.slice(0, n) })
+      } else if (/chunked/i.test(h.headers['transfer-encoding'] || '')) {
+        const b = decodeChunked(h.rest)
+        if (b) return finish(null, { status: h.status, headers: h.headers, body: b })
+      }
+      if (final) finish(null, { status: h.status, headers: h.headers, body: h.rest })
+    }
+    sock.on('data', (c) => {
+      chunks.push(c)
+      total += c.length
+      if (total > MAX_MESSAGE) return finish(new Error('response too large'))
+      tryParse(false)
+    })
+    sock.on('end', () => tryParse(true))
+    sock.on('close', () => tryParse(true))
+    sock.on('error', (err) => finish(err))
+  }))
+}
+
+// ---------------------------------------------------------------------------------------------
+
+let utf8
+function validUtf8 (buf) {
+  if (!utf8) utf8 = new TextDecoder('utf-8', { fatal: true })
+  try {
+    return utf8.decode(buf)
+  } catch (_) {
+    return null
+  }
+}
+
+class WebSocketClient extends EventEmitter {
+  /**
+   * @param {string} url ws:// or wss://
+   * @param {object} headers extra upgrade headers
+   * @param {{proxy?: string|URL, timeout?: number}} [options]
+   */
+  constructor (url, headers, options) {
+    super()
+    this.url = new URL(url)
+    this.headers = headers || {}
+    this.options = options || {}
+    this.readyState = 0 // 0 connecting, 1 open, 2 closing, 3 closed
+    this._buf = Buffer.alloc(0)
+    this._fragments = null
+    this._fragBytes = 0
+    this._socket = null
+    this._closeTimer = null
+    this.closeCode = null
+    process.nextTick(() => this._connect())
+  }
+
+  _connect () {
+    const t = parseUrl(this.url)
+    openSocket(t, { proxy: this.options.proxy, timeout: this.options.timeout || 15000 }).then((socket) => {
+      if (this.readyState === 3) {
+        socket.destroy()
+        return
+      }
+      this._socket = socket
+      if (socket.unref) socket.unref()
+      this._key = crypto.randomBytes(16).toString('base64')
+      const lines = [
+        `GET ${t.path} HTTP/1.1`,
+        `Host: ${t.hostHeader}`,
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Key: ${this._key}`,
+        'Sec-WebSocket-Version: 13'
+      ]
+      for (const k of Object.keys(this.headers)) lines.push(`${k}: ${this.headers[k]}`)
+      socket.write(lines.join('\r\n') + '\r\n\r\n')
+      socket.on('data', (chunk) => this._onData(chunk))
+      socket.on('error', (err) => this.emit('error', err))
+      socket.on('close', () => this._onClose())
+      socket.on('drain', () => this.emit('drain'))
+      this._upgradeTimer = setTimeout(() => {
+        if (this.readyState === 0) this._abort(new Error('upgrade timeout'))
+      }, this.options.timeout || 15000)
+      if (this._upgradeTimer.unref) this._upgradeTimer.unref()
+    }, (err) => {
+      this.emit('error', err)
+      this._onClose()
+    })
+  }
+
+  _abort (err) {
+    if (err) this.emit('error', err)
+    this.terminate()
+  }
+
+  _onClose () {
+    if (this.readyState === 3) return
+    this.readyState = 3
+    clearTimeout(this._closeTimer)
+    clearTimeout(this._upgradeTimer)
+    this.emit('close', this.closeCode)
+  }
+
+  _onData (chunk) {
+    this._buf = this._buf.length ? Buffer.concat([this._buf, chunk]) : chunk
+    if (this.readyState === 0) {
+      const h = parseHead(this._buf)
+      if (!h) {
+        if (this._buf.length > 65536) this._abort(new Error('upgrade response too large'))
+        return
+      }
+      this._buf = h.rest
+      clearTimeout(this._upgradeTimer)
+      const expected = crypto.createHash('sha1').update(this._key + GUID).digest('base64')
+      const upgrade = String(h.headers.upgrade || '').toLowerCase()
+      const connection = String(h.headers.connection || '').toLowerCase()
+      let why = null
+      if (h.status !== 101) why = `Unexpected server response: ${h.status}`
+      else if (upgrade !== 'websocket') why = 'missing Upgrade: websocket'
+      else if (!connection.split(',').map((s) => s.trim()).includes('upgrade')) why = 'missing Connection: upgrade'
+      else if (h.headers['sec-websocket-accept'] !== expected) why = 'bad Sec-WebSocket-Accept'
+      else if (h.headers['sec-websocket-extensions'] !== undefined) why = 'unrequested extension'
+      else if (h.headers['sec-websocket-protocol'] !== undefined) why = 'unrequested subprotocol'
+      if (why) return this._abort(new Error(why))
+      this.readyState = 1
+      this.emit('open')
+    }
+    this._parseFrames()
+  }
+
+  _protocolError (code) {
+    this.close(code)
+  }
+
+  _parseFrames () {
+    while (this.readyState === 1 || this.readyState === 2) {
+      const b = this._buf
+      if (b.length < 2) return
+      const fin = (b[0] & 0x80) !== 0
+      const rsv = b[0] & 0x70
+      const opcode = b[0] & 0x0f
+      const masked = (b[1] & 0x80) !== 0
+      let len = b[1] & 0x7f
+      let off = 2
+      if (rsv) return this._protocolError(1002)
+      if (masked) return this._protocolError(1002)
+      if (![0x0, 0x1, 0x2, 0x8, 0x9, 0xa].includes(opcode)) return this._protocolError(1002)
+      const control = opcode >= 0x8
+      if (control && (!fin || len > 125)) return this._protocolError(1002)
+      if (len === 126) {
+        if (b.length < 4) return
+        len = b.readUInt16BE(2)
+        off = 4
+      } else if (len === 127) {
+        if (b.length < 10) return
+        const big = b.readBigUInt64BE(2)
+        if (big > BigInt(MAX_MESSAGE)) return this._protocolError(1009)
+        len = Number(big)
+        off = 10
+      }
+      if (len > MAX_MESSAGE || this._fragBytes + len > MAX_MESSAGE) return this._protocolError(1009)
+      if (b.length < off + len) return
+      const payload = b.slice(off, off + len)
+      this._buf = b.slice(off + len)
+      this._onFrame(fin, opcode, payload)
+    }
+  }
+
+  _onFrame (fin, opcode, payload) {
+    switch (opcode) {
+      case 0x0:
+        if (!this._fragments) return this._protocolError(1002)
+        this._fragments.parts.push(payload)
+        this._fragBytes += payload.length
+        if (fin) {
+          const { op, parts } = this._fragments
+          this._fragments = null
+          this._fragBytes = 0
+          this._deliver(op, Buffer.concat(parts))
+        }
+        return
+      case 0x1:
+      case 0x2:
+        if (this._fragments) return this._protocolError(1002)
+        if (!fin) {
+          this._fragments = { op: opcode, parts: [payload] }
+          this._fragBytes = payload.length
+          return
+        }
+        this._deliver(opcode, payload)
+        return
+      case 0x8: {
+        if (payload.length === 1) return this._protocolError(1002)
+        if (payload.length > 2 && validUtf8(payload.slice(2)) === null) return this._protocolError(1007)
+        const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005
+        if (this.closeCode === null) this.closeCode = code
+        if (this.readyState === 1) {
+          this._writeFrame(0x8, payload.length >= 2 ? payload.slice(0, 2) : Buffer.alloc(0))
+          this.readyState = 2
+        }
+        if (this._socket) this._socket.end()
+        return
+      }
+      case 0x9:
+        this._writeFrame(0xa, payload)
+        this.emit('ping', payload)
+        return
+      case 0xa:
+        this.emit('pong', payload)
+        return
+      default:
+    }
+  }
+
+  _deliver (opcode, data) {
+    if (opcode === 0x1) {
+      const text = validUtf8(data)
+      if (text === null) return this._protocolError(1007)
+      this.emit('message', text)
+    } else {
+      this.emit('message', data)
+    }
+  }
+
+  _writeFrame (opcode, payload, cb) {
+    if (!this._socket || this._socket.destroyed) return false
+    const len = payload.length
+    let header
+    if (len < 126) {
+      header = Buffer.alloc(2)
+      header[1] = 0x80 | len
+    } else if (len < 65536) {
+      header = Buffer.alloc(4)
+      header[1] = 0x80 | 126
+      header.writeUInt16BE(len, 2)
+    } else {
+      header = Buffer.alloc(10)
+      header[1] = 0x80 | 127
+      header.writeBigUInt64BE(BigInt(len), 2)
+    }
+    header[0] = 0x80 | opcode
+    const mask = crypto.randomBytes(4)
+    const masked = Buffer.allocUnsafe(len)
+    for (let i = 0; i < len; i++) masked[i] = payload[i] ^ mask[i & 3]
+    return this._socket.write(Buffer.concat([header, mask, masked]), cb)
+  }
+
+  send (text, cb) {
+    if (this.readyState !== 1) return false
+    this._writeFrame(0x1, Buffer.from(String(text), 'utf8'), cb)
+    return true
+  }
+
+  /** Bytes queued in the socket but not yet written. */
+  bufferedAmount () {
+    return this._socket ? this._socket.writableLength : 0
+  }
+
+  ping () {
+    if (this.readyState !== 1) return false
+    return this._writeFrame(0x9, Buffer.alloc(0))
+  }
+
+  close (code, reason) {
+    if (this.readyState >= 2) {
+      if (this.readyState === 0) this.terminate()
+      return
+    }
+    if (this.readyState === 0) {
+      this.terminate()
+      return
+    }
+    const r = Buffer.from(String(reason || ''), 'utf8').slice(0, 123)
+    const p = Buffer.alloc(2 + r.length)
+    p.writeUInt16BE(code || 1000, 0)
+    r.copy(p, 2)
+    if (this.closeCode === null) this.closeCode = code || 1000
+    this._writeFrame(0x8, p)
+    this.readyState = 2
+    this._closeTimer = setTimeout(() => this.terminate(), CLOSE_TIMEOUT)
+    if (this._closeTimer.unref) this._closeTimer.unref()
+  }
+
+  terminate () {
+    if (this._socket) this._socket.destroy()
+    this._onClose()
+  }
+}
+
+module.exports = { WebSocketClient, httpRequest, openSocket, parseUrl, MAX_MESSAGE }

package/lib/util.js

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const PKG_DIR = path.resolve(__dirname, '..')
+
+/**
+ * The CommonJS Module class. `module.constructor` is the same object as require('module')
+ * without loading the public module facade, which on Node 18 pulls in the ES-module loader,
+ * readline and fs/promises internals at activation (NIO-024).
+ */
+function cjsModule () {
+  const M = module.constructor
+  if (typeof M === 'function' && M.prototype && typeof M.prototype.require === 'function' && typeof M._load === 'function') return M
+  return require('module')
+}
+
+function round2 (n) {
+  return Math.round(n * 100) / 100
+}
+
+function isPlainObject (v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+/** Random lowercase base-36 identifier of up to 16 characters (80 A.7). */
+function shortUuid () {
+  let s = ''
+  while (s.length < 16) s += Math.random().toString(36).slice(2)
+  return s.slice(0, 16)
+}
+
+/** Recursive autocast of env-provided module configuration (80 A.8.3). */
+function autocast (v) {
+  if (Array.isArray(v)) return v.map(autocast)
+  if (isPlainObject(v)) {
+    const out = {}
+    for (const k of Object.keys(v)) out[k] = autocast(v[k])
+    return out
+  }
+  if (typeof v !== 'string') return v
+  if (v === 'true') return true
+  if (v === 'false') return false
+  if (v === 'null') return null
+  if (v === 'undefined') return undefined
+  if (v === 'NaN') return NaN
+  if (v.trim() !== '' && !isNaN(Number(v))) return Number(v)
+  return v
+}
+
+/** The app's main script: require.main's file, else the real path of argv[1] (80 A.8.4). */
+function mainScript () {
+  try {
+    if (require.main && require.main.filename) return require.main.filename
+  } catch (_) {}
+  const arg = process.argv[1]
+  if (!arg) return null
+  try {
+    return fs.realpathSync(arg)
+  } catch (_) {
+    return path.resolve(arg)
+  }
+}
+
+/** package.json next to the main script, or 1/2 directories above (3 levels only). */
+function findPackageJson () {
+  const script = mainScript()
+  if (!script) return null
+  let dir = path.dirname(script)
+  for (let i = 0; i < 3; i++) {
+    const candidate = path.join(dir, 'package.json')
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+function readPackageJsonSync () {
+  const file = findPackageJson()
+  if (!file) return null
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (_) {
+    return null
+  }
+}
+
+/** JSON deep copy; returns undefined if the value cannot be serialised. Throws on cycles. */
+function jsonCopy (v) {
+  const s = JSON.stringify(v)
+  return s === undefined ? undefined : JSON.parse(s)
+}
+
+module.exports = {
+  cjsModule,
+  PKG_DIR,
+  round2,
+  isPlainObject,
+  shortUuid,
+  autocast,
+  mainScript,
+  findPackageJson,
+  readPackageJsonSync,
+  jsonCopy
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@aidra/pmx-io",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "9.13.0",
+  "description": "In-process instrumentation for Node.js and Bun apps run by pmx, or reporting to prodman on their own (@pm2/io compatible)",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/westonpark/pmx.git",
+    "directory": "packages/node-io"
+  },
+  "private": false,
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "bin": {
+    "pmx-io-node": "bin/pmx-io-node.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./preload.cjs": "./preload.cjs",
+    "./preload.mjs": "./preload.mjs",
+    "./standalone": "./standalone.cjs",
+    "./standalone.cjs": "./standalone.cjs",
+    "./standalone.mjs": "./standalone.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "preload.cjs",
+    "preload.mjs",
+    "standalone.cjs",
+    "standalone.mjs",
+    "bin/",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "sh ../../scripts/test-sandbox.sh node --test test/*.test.js"
+  },
+  "dependencies": {}
+}

package/preload.cjs

@@ -0,0 +1,26 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// CommonJS preload, injected by the pmx daemon with `--require` (Node) or `--preload` (Bun).
+// Activates only under pmx (80 NIO-020); any failure leaves the app untouched (NIO-023).
+// The cheap environment checks come first so that an inert preload loads nothing else.
+
+try {
+  const env = process.env
+  // Spawn duty of the daemon carried by its injected preload (20 DMN-240/253, 40 §2.1 item 1 /
+  // §2.2 item 2; cleanroom Q-NIO-031): source maps are enabled before the main module loads
+  // unless `disable_source_map_support` is true. `source_map_support` (forced) is the default.
+  if (env.PMX_IO === '1' && env.disable_source_map_support !== 'true' &&
+      typeof process.setSourceMapsEnabled === 'function') {
+    process.setSourceMapsEnabled(true)
+  }
+  // the root under the daemon (NIO-020), or a descendant / worker thread of one (NIO-291/293)
+  if ((env.PMX_IO === '1' || (!env.PMX_IO && env.PMX_IO_HUB && env.PMX_IO_STANDALONE !== '1')) &&
+      env.pmx !== 'false' && env.automation !== 'false') {
+    require('./lib/activate.js').activate()
+  }
+} catch (err) {
+  try {
+    process.stderr.write('[pmx] instrumentation disabled: ' + (err && err.message) + '\n')
+  } catch (_) {}
+}