@expo/event-log 0.0.1-init

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @expo/event-log
+
+## 0.0.1
+
+Initial Release.

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Phil Pluckthun,
+Copyright (c) 650 Industries, Inc. (aka Expo),
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+<div align="center">
+  <h2>@expo/event-log</h2>
+  <strong>Low-overhead structured event logs for Expo CLI processes</strong>
+  <br />
+  <br />
+</div>
+
+`@expo/event-log` is a structured event logger for command-line tools. It writes JSONL logs
+that can be replayed, tailed, inspected, or exported to trace formats.
+
+In short, `@expo/event-log`,
+
+- keeps logging cheap enough to leave enabled
+- writes bounded session logs to the system temporary directory
+- forwards worker and child-process events into the same session
+- lets tools and agents tap into running commands
+- derives typed event payloads through TypeScript declaration merging
+
+## Usage
+
+Install logging once when a CLI command starts:
+
+```ts
+import { installEventLogger } from '@expo/event-log';
+
+installEventLogger({ command: 'expo start -p web', version: '1.0.0' });
+```
+
+Create a logger in any package:
+
+```ts
+import { events } from '@expo/event-log';
+
+const log = events('metro');
+
+log('ready', { port: 8081 });
+
+const end = log.span('bundle', { platform: 'ios' });
+end('bundle', { cached: false });
+```
+
+Extend `EventRegistry` to type event payloads:
+
+```ts
+declare module '@expo/event-log' {
+  interface EventRegistry {
+    'metro:ready': { port: number };
+    'metro:bundle': { platform?: string; cached?: boolean };
+  }
+}
+```
+
+## CLI
+
+Use the CLI to find sessions, replay logs, or export traces:
+
+```sh
+event-log ps --json
+event-log tap "expo start" --filter metro:* --tail
+event-log export "expo start" --format chrome-trace -o trace.json
+event-log export "expo start" --format opentelemetry -o otel.json
+event-log clean --json
+```
+
+Selectors match a session by PID, command, session directory, or working directory.
+`tap` and `export` replay retained history first. `--tail` appends live events.
+
+## API
+
+- `events(category)` creates a typed logger
+- `installEventLogger(options)` installs logging for the process
+- `isEventLoggerActive()` returns the active destination, or `null`
+- `list(options)` lists known sessions
+- `tap(sessionDir, options)` replays and optionally follows a session

package/bin/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+(async function main() {
+  let cli;
+  try {
+    cli = await import('../dist/expo-event-log-cli.mjs');
+  } catch {
+    cli = require('../dist/expo-event-log-cli.js');
+  }
+
+  try {
+    process.exitCode = await cli.main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 1;
+  }
+})();

package/cli/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "expo-event-log-cli",
+  "private": true,
+  "version": "0.0.0",
+  "main": "../dist/expo-event-log-cli.js",
+  "module": "../dist/expo-event-log-cli.mjs",
+  "types": "../dist/expo-event-log-cli.d.ts",
+  "source": "../src/cli.ts",
+  "exports": {
+    ".": {
+      "types": "../dist/expo-event-log-cli.d.ts",
+      "import": "../dist/expo-event-log-cli.mjs",
+      "require": "../dist/expo-event-log-cli.js",
+      "source": "../src/cli.ts"
+    }
+  }
+}

package/dist/chunks/tap-chunk.js

@@ -0,0 +1,536 @@
+var e = require("node:console");
+
+var t = require("node:fs/promises");
+
+var n = require("node:path");
+
+var r = require("node:net");
+
+var o = require("node:readline");
+
+var i = require("node:os");
+
+var s = require("node:fs");
+
+const c = n.join(i.tmpdir(), "expo-event-log");
+
+const l = {
+  meta: "meta.json",
+  liveSocket: "live.sock",
+  ipcSocket: "ipc.sock"
+};
+
+const a = Symbol.for("@expo/event-log/session-base-dir-override");
+
+function cleanStaleSessionsSync() {
+  const e = function getSessionEntries() {
+    try {
+      const e = getSessionBaseDir();
+      return s.readdirSync(e, {
+        withFileTypes: !0
+      }).filter(e => e.isDirectory()).map(t => {
+        const r = n.join(e, t.name);
+        return {
+          dir: r,
+          meta: readMetaSync(r),
+          alive: !1
+        };
+      }).filter(e => !!e.meta && isCompatibleSessionMeta(e.meta)).map(e => ({
+        ...e,
+        alive: isPidAlive(e.meta.pid)
+      }));
+    } catch {
+      return [];
+    }
+  }();
+  const t = Date.now();
+  let r = 0;
+  for (const n of e) {
+    if (!n.alive && t - n.meta.startedAt > 6048e5) {
+      s.rmSync(n.dir, {
+        recursive: !0,
+        force: !0
+      });
+      r++;
+    }
+  }
+  const o = e.filter(e => s.existsSync(e.dir)).sort((e, t) => t.meta.startedAt - e.meta.startedAt);
+  for (const e of o.filter(e => !e.alive).slice(100)) {
+    s.rmSync(e.dir, {
+      recursive: !0,
+      force: !0
+    });
+    r++;
+  }
+  return r;
+}
+
+function readMetaSync(e) {
+  try {
+    const t = JSON.parse(s.readFileSync(n.join(e, l.meta), "utf8"));
+    return isCompatibleSessionMeta(t) ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+function getSessionBaseDir() {
+  return globalThis[a] || c;
+}
+
+function isPidAlive(e) {
+  if (!e || e === process.pid) {
+    return !0;
+  }
+  try {
+    process.kill(e, 0);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+
+function isCompatibleSessionMeta(e) {
+  return !!e && "object" == typeof e && 1 === e.formatVersion;
+}
+
+async function listSessions(e = {}) {
+  cleanStaleSessionsSync();
+  const r = getSessionBaseDir();
+  const o = await t.readdir(r, {
+    withFileTypes: !0
+  }).catch(() => []);
+  const i = [];
+  for (const e of o) {
+    if (!e.isDirectory()) {
+      continue;
+    }
+    const t = n.join(r, e.name);
+    const o = readMetaSync(t);
+    if (!o) {
+      continue;
+    }
+    i.push({
+      id: e.name,
+      pid: o.pid,
+      formatVersion: o.formatVersion,
+      alive: isPidAlive(o.pid),
+      startedAt: o.startedAt,
+      command: o.command,
+      cwd: o.cwd,
+      version: o.version,
+      origin: o.origin,
+      sessionDir: t
+    });
+  }
+  return function filterSessions(e, t) {
+    const n = t?.trim();
+    if (!n) {
+      return e;
+    }
+    const r = e.filter(e => function matchesSessionExactly(e, t) {
+      return sessionSearchValues(e).some(e => e === t);
+    }(e, n));
+    if (r.length) {
+      return r;
+    }
+    const o = n.toLowerCase();
+    return e.filter(e => sessionSearchValues(e).some(e => e.toLowerCase().includes(o)));
+  }(i, e.selector).sort((e, t) => t.startedAt - e.startedAt);
+}
+
+async function* readLines(e) {
+  let t = "";
+  for await (const n of e.createReadStream({
+    encoding: "utf8"
+  })) {
+    t += n;
+    let e = -1;
+    while ((e = t.indexOf("\n")) >= 0) {
+      const n = t.slice(0, e);
+      t = t.slice(e + 1);
+      if (n) {
+        yield n;
+      }
+    }
+  }
+  if (t) {
+    yield t;
+  }
+}
+
+function parseEventLine(e, t = {}, n = compileEventFilter(t.filter), r = parseSince(t.since)) {
+  try {
+    const t = JSON.parse(e);
+    if (!t || "string" != typeof t._e || "number" != typeof t._t) {
+      return null;
+    }
+    if (null != r && t._t < r) {
+      return null;
+    }
+    if (!matchesEventFilter(t._e, n)) {
+      return null;
+    }
+    return t;
+  } catch {
+    return null;
+  }
+}
+
+function parseSince(e) {
+  if (null == e) {
+    return;
+  }
+  if (e instanceof Date) {
+    const t = e.getTime();
+    if (Number.isFinite(t)) {
+      return t;
+    }
+    throw new Error(`Invalid since: ${e.toString()}`);
+  }
+  if ("number" == typeof e) {
+    if (!Number.isFinite(e) || e < 0) {
+      throw new Error(`Invalid since: ${e}`);
+    }
+    return normalizeUnixTimestamp(e);
+  }
+  const t = e.trim();
+  if (!t) {
+    return;
+  }
+  if (/^\d+(?:\.\d+)?$/.test(t)) {
+    return normalizeUnixTimestamp(Number(t));
+  }
+  const n = function parseDuration(e) {
+    const t = e.trim().toLowerCase();
+    if (!t) {
+      return;
+    }
+    let n = 0;
+    let r = 0;
+    const o = /(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)/gy;
+    while (r < t.length) {
+      o.lastIndex = r;
+      const e = o.exec(t);
+      if (!e) {
+        return;
+      }
+      const i = Number(e[1]);
+      if (!Number.isFinite(i)) {
+        return;
+      }
+      n += i * durationUnitToMs(e[2]);
+      r = o.lastIndex;
+      while (" " === t[r] || "," === t[r]) {
+        r++;
+      }
+    }
+    return n;
+  }(t);
+  if (null != n) {
+    return Date.now() - n;
+  }
+  const r = Date.parse(t);
+  if (Number.isFinite(r)) {
+    return r;
+  }
+  throw new Error(`Invalid since: ${e}`);
+}
+
+function compileEventFilter(e) {
+  const t = function normalizeEventFilter(e) {
+    const t = Array.isArray(e) ? e : e ? [ e ] : [];
+    return t.flatMap(e => e.split(",")).map(e => e.trim()).filter(Boolean);
+  }(e);
+  if (!t.length) {
+    return null;
+  }
+  return new RegExp(`^(?:${t.map(eventPatternToRegex).join("|")})$`);
+}
+
+function matchesEventFilter(e, t) {
+  return !t || t.test(e);
+}
+
+function formatSessionSelector(e) {
+  return `${e.pid} (${e.command})`;
+}
+
+function eventPatternToRegex(e) {
+  return (e.includes(":") || e.includes("*") ? e : `${e}:*`).split("*").map(escapeRegex).join(".*");
+}
+
+function escapeRegex(e) {
+  return e.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+function normalizeUnixTimestamp(e) {
+  return e < 1e10 ? 1e3 * e : e;
+}
+
+function durationUnitToMs(e) {
+  if ("ms" === e || "msec" === e || "msecs" === e || "millisecond" === e || "milliseconds" === e) {
+    return 1;
+  }
+  if ("s" === e || "sec" === e || "secs" === e || "second" === e || "seconds" === e) {
+    return 1e3;
+  }
+  if ("m" === e || "min" === e || "mins" === e || "minute" === e || "minutes" === e) {
+    return 6e4;
+  }
+  if ("h" === e || "hr" === e || "hrs" === e || "hour" === e || "hours" === e) {
+    return 36e5;
+  }
+  return 1;
+}
+
+function readLiveLine(e, t) {
+  if (!t) {
+    return e.next();
+  }
+  if (t.aborted) {
+    return Promise.resolve(null);
+  }
+  return new Promise(n => {
+    const onAbort = () => n(null);
+    t.addEventListener("abort", onAbort, {
+      once: !0
+    });
+    e.next().then(e => {
+      t.removeEventListener("abort", onAbort);
+      n(t.aborted ? null : e);
+    });
+  });
+}
+
+function resetAbortTimer(e, t, n) {
+  clearTimeout(e);
+  return setAbortTimer(t, n);
+}
+
+function setAbortTimer(e, t) {
+  const n = setTimeout(() => e.abort(), t);
+  n.unref?.();
+  return n;
+}
+
+function sessionSearchValues(e) {
+  return [ e.id, String(e.pid), e.sessionDir, e.cwd, e.command, e.origin?.cwd, e.origin?.argv.join(" "), e.origin?.execPath, e.origin?.env?.npmLifecycleEvent, e.origin?.env?.npmPackageName ].filter(e => !!e);
+}
+
+function tryConnect(e, t) {
+  return new Promise(n => {
+    const o = r.connect(e);
+    const cleanup = () => {
+      o.off("connect", onConnect);
+      o.off("error", onError);
+      t?.removeEventListener("abort", onAbort);
+    };
+    const onConnect = () => {
+      cleanup();
+      n(o);
+    };
+    const onError = () => {
+      cleanup();
+      o.destroy();
+      n(null);
+    };
+    const onAbort = () => {
+      cleanup();
+      o.destroy();
+      n(null);
+    };
+    o.once("connect", onConnect);
+    o.once("error", onError);
+    t?.addEventListener("abort", onAbort, {
+      once: !0
+    });
+  });
+}
+
+exports.DEFAULT_SEGMENTS = 3;
+
+exports.DEFAULT_SEGMENT_SIZE = 524288;
+
+exports.EVENT_LOG_FORMAT_VERSION = 1;
+
+exports.EVENT_LOG_STATE_VERSION = 1;
+
+exports.INTERNAL_IPC_ENV = "__eventLogIpc";
+
+exports.INTERNAL_PROCESS_ORIGIN_ENV = "__eventLogProcessOrigin";
+
+exports.LOG_EVENTS_ENV = "LOG_EVENTS";
+
+exports.SESSION_FILES = l;
+
+exports.cleanStaleSessionsSync = cleanStaleSessionsSync;
+
+exports.compileEventFilter = compileEventFilter;
+
+exports.getSessionBaseDir = getSessionBaseDir;
+
+exports.listSessions = listSessions;
+
+exports.matchesEventFilter = matchesEventFilter;
+
+exports.parseEventLine = parseEventLine;
+
+exports.parseSince = parseSince;
+
+exports.redirectConsoleForFd = function redirectConsoleForFd(t) {
+  if (1 === t) {
+    const t = process.stderr;
+    Object.defineProperty(process, "stdout", {
+      get: () => t
+    });
+    globalThis.console = new e.Console(t, t);
+  } else if (2 === t) {
+    const t = process.stdout;
+    Object.defineProperty(process, "stderr", {
+      get: () => t
+    });
+    globalThis.console = new e.Console(t, t);
+  }
+};
+
+exports.redirectConsoleToStderr = function redirectConsoleToStderr() {
+  globalThis.console = new e.Console(process.stderr, process.stderr);
+};
+
+exports.resolveSession = async function resolveSession(e) {
+  const t = await listSessions({
+    selector: e
+  });
+  const n = 1 === t.length ? t[0] : null;
+  if (!n) {
+    throw new Error(null != e ? t.length ? `Ambiguous event-log session "${e}"; specify one of: ${t.map(formatSessionSelector).join(", ")}` : `No event-log session matching "${e}"` : t.length ? `Ambiguous event-log session; specify one of: ${t.map(formatSessionSelector).join(", ")}` : "No event-log sessions found");
+  }
+  return n;
+};
+
+exports.tap = async function* tap(e, r = {}) {
+  const i = !0 === r.follow;
+  const s = parseSince(r.since);
+  const c = compileEventFilter(r.filter);
+  const a = function createTapAbortController(e, t) {
+    if (!t || null == e.timeout && null == e.idleTimeout) {
+      return;
+    }
+    const n = new AbortController;
+    e.signal?.addEventListener("abort", () => n.abort(), {
+      once: !0
+    });
+    if (null != e.timeout) {
+      setAbortTimer(n, e.timeout);
+    }
+    return n;
+  }(r, i);
+  const u = a?.signal ?? r.signal;
+  const f = i ? await async function connectLive(e, t) {
+    const r = n.join(e, l.liveSocket);
+    const i = await async function connectWithRetry(e, t) {
+      for (let n = 0; n < 20 && !t?.aborted; n++) {
+        const n = await tryConnect(e, t);
+        if (n) {
+          return n;
+        }
+        await new Promise(e => setTimeout(e, 50));
+      }
+      return null;
+    }(r, t);
+    if (!i) {
+      return;
+    }
+    const s = o.createInterface({
+      input: i
+    });
+    const c = [];
+    const a = [];
+    let u = !1;
+    const push = e => {
+      const t = a.shift();
+      if (t) {
+        t(e);
+      } else if (null != e) {
+        c.push(e);
+      }
+    };
+    s.on("line", e => push(e));
+    s.on("close", () => {
+      u = !0;
+      push(null);
+    });
+    i.on("error", () => {
+      u = !0;
+      push(null);
+    });
+    t?.addEventListener("abort", () => i.destroy(), {
+      once: !0
+    });
+    return {
+      buffer: c,
+      next() {
+        if (c.length) {
+          return Promise.resolve(c.shift());
+        }
+        if (u) {
+          return Promise.resolve(null);
+        }
+        return new Promise(e => a.push(e));
+      }
+    };
+  }(e, u) : void 0;
+  const m = await async function openHistoryFiles(e) {
+    const r = readMetaSync(e)?.maxSegments ?? 3;
+    const o = await Promise.all(Array.from({
+      length: r
+    }, (r, o) => t.open(n.join(e, `${o}.jsonl`), "r").catch(() => null)));
+    return o.filter(e => null != e).reverse();
+  }(e);
+  let d;
+  try {
+    for (const e of m) {
+      for await (const t of readLines(e)) {
+        const e = parseEventLine(t, r, c, s);
+        if (e) {
+          yield e;
+        }
+      }
+    }
+  } finally {
+    await Promise.all(m.map(e => e.close().catch(() => {})));
+  }
+  if (!f) {
+    return;
+  }
+  if (null != r.idleTimeout && a) {
+    d = setAbortTimer(a, r.idleTimeout);
+  }
+  for (const e of f.buffer.splice(0)) {
+    const t = parseEventLine(e, r, c, s);
+    if (t) {
+      if (d) {
+        d = resetAbortTimer(d, a, r.idleTimeout);
+      }
+      yield t;
+    }
+  }
+  while (!u?.aborted) {
+    const e = await readLiveLine(f, u);
+    if (null == e) {
+      break;
+    }
+    if (d) {
+      d = resetAbortTimer(d, a, r.idleTimeout);
+    }
+    const t = parseEventLine(e, r, c, s);
+    if (t) {
+      yield t;
+    }
+  }
+  if (d) {
+    clearTimeout(d);
+  }
+};
+//# sourceMappingURL=tap-chunk.js.map