@aidra/pmx-io 0.0.0-stage → 9.13.0

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @aidra/pmx-io
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+In-process instrumentation for Node.js and Bun apps that report to
+[prodman](https://github.com/westonpark/prodman): metrics, custom actions, exceptions, events,
+logs, CPU and heap profiling, and distributed tracing with database and message-broker
+integrations. It keeps the `@pm2/io` API, so code written for PM2.io works unchanged.
+
+* **Run by pmx:** pmx injects this library into every app it starts; nothing to install. An
+  installed copy stays idle and `require` returns the injected instance.
+* **Run by PM2 / pm2_prodman:** reports through the PM2 daemon, like `@pm2/io`.
+* **Standalone** (a container's `node app.js`, an ECS task, a worker): connects to prodman
+  itself as a one-process agent.
+
+Node.js 18 or later, or Bun 1.1 or later. No dependencies.
+
+## Install
+
+```sh
+npm install @aidra/pmx-io
+```
+
+Code that requires `@pm2/io` can keep doing so: install the package under that name.
+
+```sh
+npm install @pm2/io@npm:@aidra/pmx-io
+```
+
+## Standalone mode
+
+Set the bucket keys (prodman: *Bucket settings → Connect servers*) and an app name:
+
+```sh
+PRODMAN_URL=https://prodman.example.com
+PM2_PUBLIC_KEY=<public key>
+PM2_SECRET_KEY=<secret key>
+PM2_APP_NAME=orders-api
+```
+
+Then load the library without changing code:
+
+```sh
+npx pmx-io-node run -- node server.js
+node --require @aidra/pmx-io/standalone server.js
+NODE_OPTIONS='--import @aidra/pmx-io/standalone.mjs' node server.mjs
+```
+
+or require it first thing in the app:
+
+```js
+const io = require('@aidra/pmx-io')
+io.init({ apmOptions: { sendLogs: true, application: 'shop' } })
+```
+
+Settings, server names, containers and troubleshooting: prodman's documentation page
+*Node.js apps without pmx* (`/docs/node-apm`).
+
+## API
+
+```js
+const io = require('@aidra/pmx-io')
+
+io.metric({ name: 'Queue length' }).set(12)
+io.counter({ name: 'Jobs done' }).inc()
+io.action('flush cache', (reply) => reply({ ok: true }))
+io.notifyError(new Error('payment failed'), { custom: { orderId } })
+```
+
+TypeScript declarations are included (`index.d.ts`), a superset of `@pm2/io`'s.
+
+Proprietary. © 2026 Mike Warriner.

package/bin/pmx-io-node.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The standalone launcher (80 NIO-261): `pmx-io-node run [--] <command> [args…]`. Never
+// activates the library. Prepends the standalone preload to NODE_OPTIONS (plus `--import` of
+// standalone.mjs when env trace=true and the Node runs module hooks), sets PMX_IO_STANDALONE=1
+// and PMX_IO_ROOT_PID=<its pid>, inserts `--preload <abs>/standalone.cjs` after a `bun` command,
+// then replaces itself with the command through process.execve (same pid: signals reach the app,
+// its exit status is the app's). With PMX_IO_OTEL_EXPORT=1 it also sets the OTEL_* variables
+// that point an app's own OpenTelemetry SDK at prodman (85 OTX-052, lib/otel/env.js).
+// Without process.execve it spawns the command with inherited
+// stdio, names itself PMX_IO_ROOT_PPID (the child becomes the root), forwards signals and exits
+// with the child's status.
+
+const path = require('path')
+const fs = require('fs')
+const { pathToFileURL } = require('url')
+
+const PKG = path.resolve(__dirname, '..')
+const CJS = path.join(PKG, 'standalone.cjs')
+const MJS = path.join(PKG, 'standalone.mjs')
+const FORWARDED = ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR1', 'SIGUSR2']
+const USAGE = 'usage: pmx-io-node run [--] <command> [args...]\n' +
+  '  Runs <command> with @aidra/pmx-io in standalone mode (reports to prodman without pmx).\n' +
+  '  Needs PM2_PUBLIC_KEY, PM2_SECRET_KEY and PM2_APP_NAME (and PRODMAN_URL) in the environment.\n'
+
+function quote (p) {
+  return '"' + p.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+/** Node ≥ 18.19 / ≥ 20.6 runs --import preloads (INJ-010 rule). */
+function supportsImport () {
+  const [a, b] = process.versions.node.split('.').map(Number)
+  return (a === 18 && b >= 19) || (a === 20 && b >= 6) || a > 20
+}
+
+function isBun (cmd) {
+  const base = path.basename(cmd)
+  return base === 'bun' || base.endsWith('bun')
+}
+
+function which (cmd) {
+  if (cmd.includes('/')) return cmd
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue
+    const full = path.join(dir, cmd)
+    try {
+      fs.accessSync(full, fs.constants.X_OK)
+      if (fs.statSync(full).isFile()) return full
+    } catch (_) {}
+  }
+  return null
+}
+
+function prepare (argv, env) {
+  const tokens = [`--require ${quote(CJS)}`]
+  if (env.trace === 'true' && supportsImport()) tokens.push(`--import ${quote(pathToFileURL(MJS).href)}`)
+  const cur = env.NODE_OPTIONS || ''
+  if (!cur.includes(CJS)) env.NODE_OPTIONS = tokens.join(' ') + (cur ? ' ' + cur : '')
+  env.PMX_IO_STANDALONE = '1'
+  if (env.PMX_IO_OTEL_EXPORT === '1') {
+    // 85 OTX-052: wire the app's own OpenTelemetry SDK to prodman's OTLP endpoint (opt-in)
+    try {
+      require('../lib/otel/env').wireLauncher(env)
+    } catch (err) {
+      process.stderr.write('pmx-io-node: OpenTelemetry wiring failed: ' + (err && err.message) + '\n')
+    }
+  }
+  const args = argv.slice()
+  if (isBun(args[0]) && !args.includes(CJS)) args.splice(1, 0, '--preload', CJS)
+  return args
+}
+
+function main (argv) {
+  let rest = argv.slice(2)
+  if (rest[0] !== 'run') {
+    process.stderr.write(USAGE)
+    return 2
+  }
+  rest = rest.slice(1)
+  if (rest[0] === '--') rest = rest.slice(1)
+  if (rest.length === 0) {
+    process.stderr.write(USAGE)
+    return 2
+  }
+  const env = Object.assign({}, process.env)
+  delete env.PMX_IO_ROOT_PPID
+  const args = prepare(rest, env)
+  const file = which(args[0])
+  if (!file) {
+    process.stderr.write(`pmx-io-node: ${args[0]}: command not found\n`)
+    return 127
+  }
+  if (typeof process.execve === 'function' && env.PMX_IO_LAUNCHER_NO_EXECVE !== '1') {
+    env.PMX_IO_ROOT_PID = String(process.pid)
+    try {
+      process.execve(file, args, env)
+    } catch (err) {
+      process.stderr.write(`pmx-io-node: cannot run ${args[0]}: ${err && err.message}\n`)
+      return 126
+    }
+  }
+  // fallback: a parent process
+  delete env.PMX_IO_ROOT_PID
+  env.PMX_IO_ROOT_PPID = String(process.pid)
+  const { spawn } = require('child_process')
+  const child = spawn(file, args.slice(1), { stdio: 'inherit', env, argv0: args[0] })
+  for (const sig of FORWARDED) {
+    try {
+      process.on(sig, () => {
+        try {
+          child.kill(sig)
+        } catch (_) {}
+      })
+    } catch (_) {}
+  }
+  child.on('error', (err) => {
+    process.stderr.write(`pmx-io-node: cannot run ${args[0]}: ${err && err.message}\n`)
+    process.exit(126)
+  })
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      const n = require('os').constants.signals[signal] || 1
+      if (process.pid === 1) process.exit(128 + n)
+      for (const sig of FORWARDED) process.removeAllListeners(sig)
+      try {
+        process.kill(process.pid, signal)
+      } catch (_) {}
+      setTimeout(() => process.exit(128 + n), 100)
+      return
+    }
+    process.exit(code === null ? 1 : code)
+  })
+  return null
+}
+
+if (require.main === module) {
+  const code = main(process.argv)
+  if (code !== null && code !== undefined) process.exitCode = code
+}
+
+module.exports = { main, prepare, isBun }

package/index.d.ts

@@ -0,0 +1,381 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+
+// Type declarations for @aidra/pmx-io. The surface is a superset of @pm2/io's public API
+// (80 NIO-001), so `import io from '@pm2/io'` code type-checks against this package.
+
+export type MetricMeasurement =
+  | 'min' | 'max' | 'sum' | 'count' | 'variance' | 'mean' | 'stddev'
+  | 'median' | 'p75' | 'p95' | 'p99' | 'p999' | 'ema'
+
+export declare const MetricMeasurements: { readonly [K in MetricMeasurement]: K }
+export declare const MetricType: {
+  readonly meter: 'meter'
+  readonly histogram: 'histogram'
+  readonly counter: 'counter'
+  readonly gauge: 'gauge'
+  readonly metric: 'metric'
+}
+
+export interface MetricOptions {
+  /** Metric name; the key in axm:monitor. */
+  name: string
+  /** Free-form type label, reported as `type`. */
+  id?: string
+  unit?: string
+  /** Whether history is kept (default true). */
+  historic?: boolean
+}
+
+export interface GaugeOptions extends MetricOptions {
+  /** Passive gauge: evaluated at every push. */
+  value?: () => number | string | boolean | null | undefined
+}
+
+export interface CounterOptions extends MetricOptions {
+  count?: number
+}
+
+export interface MeterOptions extends MetricOptions {
+  /** Rate unit in seconds (default 1). */
+  samples?: number
+  seconds?: number
+  /** Averaging window in seconds (default 60). */
+  timeframe?: number
+  /** Tick interval in ms (default 5000). */
+  tickInterval?: number
+}
+
+export interface HistogramOptions extends MetricOptions {
+  measurement?: MetricMeasurement
+}
+
+export interface MetricBulkOptions extends GaugeOptions, CounterOptions, MeterOptions, HistogramOptions {
+  type?: 'counter' | 'gauge' | 'histogram' | 'meter' | 'metric'
+}
+
+export declare class Gauge {
+  set (value: number | string | boolean): void
+  val (): any
+  isUsed (): boolean
+}
+
+export declare class Counter {
+  inc (n?: number): void
+  dec (n?: number): void
+  reset (count?: number): void
+  val (): number
+  isUsed (): boolean
+}
+
+export declare class Meter {
+  mark (n?: number): void
+  val (): number
+  isUsed (): boolean
+}
+
+export interface HistogramResults {
+  min: number | null
+  max: number | null
+  sum: number
+  variance: number | null
+  mean: number
+  count: number
+  median: number | null
+  p75: number | null
+  p95: number | null
+  p99: number | null
+  p999: number | null
+  ema: number
+}
+
+export declare class Histogram {
+  update (value: number): void
+  val (): number | null
+  percentiles (fractions: number[]): { [fraction: number]: number | null }
+  fullResults (): HistogramResults
+  getMin (): number | null
+  getMax (): number | null
+  getSum (): number
+  getCount (): number
+  getEma (): number
+  isUsed (): boolean
+}
+
+export interface IOConfig {
+  catchExceptions?: boolean
+  profiling?: boolean | {
+    cpuJS?: boolean
+    heapSnapshot?: boolean
+    heapSampling?: boolean
+    implementation?: 'inspector' | 'addon' | 'both' | 'none'
+  }
+  metrics?: {
+    eventLoop?: boolean | { eventLoopActive?: boolean, eventLoopDelay?: boolean }
+    network?: boolean | { upload?: boolean, download?: boolean }
+    http?: boolean
+    /** `HTTP Outbound*` metrics (80 NIO-055), default true */
+    httpOutbound?: boolean
+    runtime?: boolean | { gcNewPause?: boolean, gcOldPause?: boolean, pageFaults?: boolean, contextSwitchs?: boolean }
+    v8?: boolean | { [key: string]: boolean }
+    fds?: boolean
+  }
+  actions?: { eventLoopDump?: boolean }
+  standalone?: boolean
+  /**
+   * The prodman application this process belongs to (pmx 97 PAP-050): 1-63 of `[a-z0-9._-]`,
+   * case-insensitive. Standalone only (init > `PMX_APPLICATION` > `default`); under pmx the
+   * daemon decides and a differing value is ignored with a warning.
+   */
+  application?: string
+  apmOptions?: {
+    url?: string
+    publicKey?: string
+    secretKey?: string
+    appName?: string
+    serverName?: string
+    sendLogs?: boolean
+    disableLogs?: boolean
+    logFilter?: string | RegExp
+    /** standalone log capture (80 NIO-267), default 'stdio' */
+    captureLogs?: 'stdio' | 'off'
+    /** `http://[user:pass@]host:port` (default env PMX_IO_PROXY) */
+    proxy?: string
+  }
+  tracing?: boolean | TracingConfig
+  /** report exceptions that frameworks turn into ≥ 500 responses (80 NIO-223), default true */
+  httpErrors?: boolean
+  /** instrument Node descendants and worker threads through this process (80 NIO-290), default true */
+  children?: boolean
+  [key: string]: any
+}
+
+export type UrlMatcher = string | RegExp | ((url: string, request: any) => boolean)
+
+export interface TracingConfig {
+  /** default true when the object is given */
+  enabled?: boolean
+  serviceName?: string
+  /** false: no CLIENT spans for outbound HTTP */
+  outbound?: boolean
+  /** accepted and ignored (A.6 quirk); use sampleRatio */
+  samplingRate?: number
+  ignoreIncomingPaths?: UrlMatcher[]
+  ignoreOutgoingUrls?: UrlMatcher[]
+  /** trace-id-ratio sampling of new traces, [0, 1], default 1 (80 NIO-205) */
+  sampleRatio?: number
+  /** default true (80 NIO-205) */
+  exportUnsampledErrors?: boolean
+  /** export rate limit, default 2000, 0 = unlimited (80 NIO-206) */
+  maxSpansPerSecond?: number
+  /** duration floor in µs, default 1000 (0 with NODE_ENV=test) */
+  minDurationUs?: number
+  db?: boolean | {
+    statement?: 'sanitized' | 'raw' | 'off',
+    poolSpans?: boolean,
+    /** Trace comment on SQL statements / MongoDB commands of sampled traces (default 'on'; env PMX_DB_COMMENT). */
+    comment?: 'on' | 'off' | 'force',
+    /** Set PostgreSQL application_name / MongoDB appName to the app name when the app set none (default true). */
+    applicationName?: boolean
+  }
+  messaging?: boolean | { rootProducers?: boolean, redisStreamFields?: boolean, payloadCarrier?: boolean, maxLinks?: number }
+  logCorrelation?: boolean | { console?: boolean }
+  baggageTags?: string[]
+  /** route-less SERVER span names normalised (80 Part G.2), default true */
+  normalizePaths?: boolean
+  createSpanWithNet?: boolean
+  detailedDatabasesCalls?: boolean
+  [key: string]: any
+}
+
+/** OpenTelemetry-compatible numbers are accepted too: 0 internal … 4 consumer. */
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer' | string | 0 | 1 | 2 | 3 | 4
+
+export type Carrier =
+  | { [name: string]: any }
+  | Map<string, any>
+  | Array<[string, any]>
+  | { get (name: string): any }
+  | { set (name: string, value: any): any, has (name: string): boolean }
+
+/** The W3C trace context of a span (80 NIO-240). */
+export declare class SpanContext {
+  constructor (opts: { traceId: string, spanId: string, sampled?: boolean, traceState?: string | null, baggage?: { [k: string]: string }, isRemote?: boolean })
+  readonly traceId: string
+  readonly spanId: string
+  readonly sampled: boolean
+  readonly traceState: string | null
+  readonly baggage: Readonly<{ [k: string]: string }>
+  readonly isRemote: boolean
+  traceparent (): string
+}
+
+export type Link = SpanContext | { context: SpanContext, attributes?: { [k: string]: any } }
+
+export interface SpanOptions {
+  kind?: SpanKind
+  attributes?: { [k: string]: any }
+  /** undefined: the current span (or a new trace); a Span; a SpanContext; or NEW_TRACE */
+  parent?: Span | SpanContext | typeof NEW_TRACE
+  links?: Link[]
+  /** ms since the epoch */
+  startTime?: number | Date
+}
+
+export interface Span {
+  /** null for the no-op span (tracing disabled) */
+  readonly context: SpanContext | null
+  setAttribute (key: string, value: any): this
+  setAttributes (attributes: { [k: string]: any }): this
+  addEvent (name: string): this
+  addLink (context: SpanContext, attributes?: { [k: string]: any }): this
+  recordException (error: any): this
+  setStatus (status: 'OK' | 'ERROR' | 'UNSET' | string | { code: 0 | 1 | 2, message?: string }, message?: string): this
+  end (endTime?: number | Date): void
+  isRecording (): boolean
+  traceparent (): string | null
+}
+
+export interface Tracer {
+  readonly enabled: boolean
+  startSpan (name: string, options?: SpanOptions): Span
+  /** runs fn with the span current; the span ends when fn returns, throws or its promise settles */
+  startActiveSpan<T> (name: string, fn: (span: Span) => T): T
+  startActiveSpan<T> (name: string, options: SpanOptions, fn: (span: Span) => T): T
+  withSpan<T> (span: Span, fn: (span: Span) => T): T
+  currentSpan (): Span | undefined
+}
+
+export interface InjectOptions {
+  context?: SpanContext
+  overwrite?: boolean
+  asBytes?: boolean
+}
+
+export interface ConsumerSpanOptions {
+  name?: string
+  system?: string
+  destination?: string
+  attributes?: { [k: string]: any }
+}
+
+export interface TraceContextFields {
+  trace_id?: string
+  span_id?: string
+  trace_sampled?: boolean
+}
+
+/** As `parent`, starts a new trace even inside a span (80 NIO-247). */
+export declare const NEW_TRACE: { readonly __newTrace?: never }
+
+export type ActionReply = (data: any) => void
+export type ActionHandler =
+  | ((reply: ActionReply) => any)
+  | ((params: any, reply: ActionReply) => any)
+
+export interface ScopedActionStream {
+  send (data: any): void
+  error (data: any): void
+  end (data: any): void
+}
+
+export interface ErrorContext {
+  http?: { [key: string]: any }
+  custom?: { [key: string]: any }
+  [key: string]: any
+}
+
+export declare class Entrypoint {
+  io: PMX
+  constructor ()
+  onStart (cb: (err?: Error) => void): void
+  onStop (err: Error | undefined, cb: () => void, code: number | null, signal: string | null): void
+  sensors (): void
+  events (): void
+  actuators (): void
+  conf (): IOConfig | undefined
+}
+
+export interface Probe {
+  metric (opts: GaugeOptions | string): Gauge | undefined
+  gauge (opts: GaugeOptions | string): Gauge | undefined
+  counter (opts: CounterOptions | string): Counter | undefined
+  meter (opts: MeterOptions | string): Meter | undefined
+  histogram (opts: HistogramOptions | string): Histogram | undefined
+  transpose (name: string | { name: string, data: () => any }, fn?: () => any): void
+}
+
+export interface PMX {
+  init (config?: IOConfig): PMX
+  destroy (): void
+  getConfig (): IOConfig | undefined
+  notifyError (err: Error | any, context?: ErrorContext): void
+  /** Legacy alias of notifyError. */
+  notify (err: Error | any, context?: ErrorContext): void
+  metric (opts: GaugeOptions | string): Gauge | undefined
+  gauge (opts: GaugeOptions | string): Gauge | undefined
+  counter (opts: CounterOptions | string): Counter | undefined
+  meter (opts: MeterOptions | string): Meter | undefined
+  histogram (opts: HistogramOptions | string): Histogram | undefined
+  metrics (defs: MetricBulkOptions | MetricBulkOptions[]): any[]
+  probe (): Probe
+  transpose (name: string | { name: string, data: () => any }, fn?: () => any): void
+  action (name: string, handler: ActionHandler): void
+  action (name: string, opts: any, handler: ActionHandler): void
+  action (def: { name: string, options?: any, action: ActionHandler }): void
+  scopedAction (name: string, handler: (params: any, stream: ScopedActionStream) => any): void
+  emit (name: string, data: { [key: string]: any }): void
+  onExit (callback: (code: number | null, signal: string | null) => any): void
+  getTracer (): Tracer
+  inject<C extends Carrier> (carrier: C, options?: InjectOptions): C
+  extract (carrier: Carrier): SpanContext | null
+  getBaggage (): Readonly<{ [k: string]: string }>
+  withBaggage<T> (entries: { [k: string]: any }, fn: () => T): T
+  wrap<F extends (...args: any[]) => any> (fn: F): F
+  traceContext (): TraceContextFields
+  consumerSpan<T> (carrier: Carrier, options: ConsumerSpanOptions, fn: (span: Span) => T): T
+  SpanContext: typeof SpanContext
+  NEW_TRACE: typeof NEW_TRACE
+  initModule (opts?: any, cb?: (err: Error | null, conf: any) => void): any
+  configureModule (opts: { [key: string]: any }): void
+  expressErrorHandler (): (err: any, req: any, res: any, next: (err?: any) => void) => void
+  koaErrorHandler (): (ctx: any, next: () => Promise<any>) => Promise<void>
+  Entrypoint: typeof Entrypoint
+  MetricType: typeof MetricType
+  MetricMeasurements: typeof MetricMeasurements
+  version: string
+}
+
+export declare function init (config?: IOConfig): PMX
+export declare function destroy (): void
+export declare function getConfig (): IOConfig | undefined
+export declare function notifyError (err: Error | any, context?: ErrorContext): void
+export declare function notify (err: Error | any, context?: ErrorContext): void
+export declare function metric (opts: GaugeOptions | string): Gauge | undefined
+export declare function gauge (opts: GaugeOptions | string): Gauge | undefined
+export declare function counter (opts: CounterOptions | string): Counter | undefined
+export declare function meter (opts: MeterOptions | string): Meter | undefined
+export declare function histogram (opts: HistogramOptions | string): Histogram | undefined
+export declare function metrics (defs: MetricBulkOptions | MetricBulkOptions[]): any[]
+export declare function probe (): Probe
+export declare function transpose (name: string | { name: string, data: () => any }, fn?: () => any): void
+export declare function action (name: string, handler: ActionHandler): void
+export declare function action (name: string, opts: any, handler: ActionHandler): void
+export declare function action (def: { name: string, options?: any, action: ActionHandler }): void
+export declare function scopedAction (name: string, handler: (params: any, stream: ScopedActionStream) => any): void
+export declare function emit (name: string, data: { [key: string]: any }): void
+export declare function onExit (callback: (code: number | null, signal: string | null) => any): void
+export declare function getTracer (): Tracer
+export declare function inject<C extends Carrier> (carrier: C, options?: InjectOptions): C
+export declare function extract (carrier: Carrier): SpanContext | null
+export declare function getBaggage (): Readonly<{ [k: string]: string }>
+export declare function withBaggage<T> (entries: { [k: string]: any }, fn: () => T): T
+export declare function wrap<F extends (...args: any[]) => any> (fn: F): F
+export declare function traceContext (): TraceContextFields
+export declare function consumerSpan<T> (carrier: Carrier, options: ConsumerSpanOptions, fn: (span: Span) => T): T
+export declare function initModule (opts?: any, cb?: (err: Error | null, conf: any) => void): any
+export declare function configureModule (opts: { [key: string]: any }): void
+export declare function expressErrorHandler (): (err: any, req: any, res: any, next: (err?: any) => void) => void
+export declare function koaErrorHandler (): (ctx: any, next: () => Promise<any>) => Promise<void>
+
+declare const io: PMX
+export default io

package/index.js

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// Public entry (CommonJS). The module value is the process-wide instance stored under
+// Symbol.for('@pm2/io') (80 IO-001): when an instance already exists (the one injected by
+// pmx, or any compatible copy) it is returned and nothing new is created; otherwise a new
+// instance is created, initialised with the default configuration and stored.
+
+const SYMBOL = Symbol.for('@pm2/io')
+
+let instance
+if (Object.prototype.hasOwnProperty.call(globalThis, SYMBOL)) {
+  instance = globalThis[SYMBOL]
+} else {
+  const { PMX } = require('./lib/pmx')
+  instance = new PMX()
+  Object.defineProperty(globalThis, SYMBOL, { value: instance, writable: true, configurable: true, enumerable: false })
+  try {
+    instance.init()
+  } catch (err) {
+    try {
+      process.stderr.write('[@pm2/io] initialisation failed: ' + (err && err.message) + '\n')
+    } catch (_) {}
+  }
+}
+
+module.exports = instance

package/index.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+
+// Public entry (ES module): the default export is the process-wide instance (the same object
+// as require('@aidra/pmx-io')); every API method is also a named export (80 NIO-002).
+
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const io = require('./index.js')
+
+const call = (name) => (...args) => (typeof io[name] === 'function' ? io[name](...args) : undefined)
+
+export default io
+export const init = call('init')
+export const destroy = call('destroy')
+export const getConfig = call('getConfig')
+export const notifyError = call('notifyError')
+export const notify = call('notify')
+export const metric = call('metric')
+export const gauge = call('gauge')
+export const counter = call('counter')
+export const meter = call('meter')
+export const histogram = call('histogram')
+export const metrics = call('metrics')
+export const probe = call('probe')
+export const transpose = call('transpose')
+export const action = call('action')
+export const scopedAction = call('scopedAction')
+export const emit = call('emit')
+export const onExit = call('onExit')
+export const getTracer = call('getTracer')
+export const initModule = call('initModule')
+export const expressErrorHandler = call('expressErrorHandler')
+export const koaErrorHandler = call('koaErrorHandler')
+export const configureModule = call('configureModule')
+export const inject = call('inject')
+export const extract = call('extract')
+export const getBaggage = call('getBaggage')
+export const withBaggage = call('withBaggage')
+export const wrap = call('wrap')
+export const traceContext = call('traceContext')
+export const consumerSpan = call('consumerSpan')
+export const SpanContext = io.SpanContext
+export const NEW_TRACE = io.NEW_TRACE
+export const Entrypoint = io.Entrypoint
+export const MetricType = io.MetricType
+export const MetricMeasurements = io.MetricMeasurements