2g 0.3.1 → 0.4.0

package/dist/chunks/cli-chunk.js

@@ -8,13 +8,15 @@ var s = require("./pretty-chunk.js");
 
 var o = require("node:fs");
 
-var r = require("./tap-chunk.js");
+var r = require("./api-chunk.js");
 
 var i = require("node:readline");
 
 var a = require("node:crypto");
 
-var l = "undefined" != typeof document ? document.currentScript : null;
+var l = require("node:child_process");
+
+var c = "undefined" != typeof document ? document.currentScript : null;
 
 function runCleanCli(e = []) {
   const o = function parseCleanOptions(e) {
@@ -48,7 +50,7 @@ function runCleanCli(e = []) {
   })}\n` : `Removed ${r} ${o.all ? "exited" : "stale"} sessions.\n`);
 }
 
-const c = {
+const p = {
   since: {
     type: "string"
   },
@@ -67,6 +69,13 @@ const c = {
   }
 };
 
+async function warnOnRotationLoss(e, t) {
+  if (!await r.detectRotationLoss(e)) {
+    return;
+  }
+  console.warn(`⚠ Earlier events were rotated out of the retained window.\n  For a complete trace, start \`${t}\` before the workload.`);
+}
+
 async function* readJsonlStream(e) {
   const t = i.createInterface({
     input: e
@@ -84,6 +93,21 @@ async function* readJsonlStream(e) {
   }
 }
 
+async function* filterEvents(e, t) {
+  const s = n.compileEventFilter(t.filter);
+  const o = n.parseSince(t.since);
+  for await (const r of e) {
+    if (n.matchesTapOptions(r, {
+      filter: t.filter,
+      since: o,
+      spans: t.spans,
+      debug: t.debug
+    }, s)) {
+      yield r;
+    }
+  }
+}
+
 function parseSharedTapOptions(e) {
   return {
     since: e.since,
@@ -108,7 +132,15 @@ function parseHelp(e) {
   }).values.help;
 }
 
-const p = [ ":started", ":done", ":failed" ];
+const u = [ ":started", ":done", ":failed" ];
+
+async function convertToChromeTrace(e, t = {}) {
+  const n = new TraceConverter(t);
+  for await (const t of e) {
+    n.add(t);
+  }
+  return n.toTraceFile();
+}
 
 class TraceConverter {
   #e=[];
@@ -297,7 +329,7 @@ function assignLanes(e) {
 }
 
 function stripSuffix$1(e) {
-  for (const t of p) {
+  for (const t of u) {
     if (e.endsWith(t)) {
       return e.slice(0, -t.length);
     }
@@ -305,7 +337,15 @@ function stripSuffix$1(e) {
   return e;
 }
 
-const u = [ ":started", ":done", ":failed" ];
+const d = [ ":started", ":done", ":failed" ];
+
+async function convertToOpenTelemetry(e, t = {}) {
+  const n = new OpenTelemetryConverter(t);
+  for await (const t of e) {
+    n.add(t);
+  }
+  return n.toFile();
+}
 
 class OpenTelemetryConverter {
   #i=a.randomBytes(16).toString("hex");
@@ -491,7 +531,7 @@ function splitEventName(e) {
 }
 
 function stripSuffix(e) {
-  for (const t of u) {
+  for (const t of d) {
     if (e.endsWith(t)) {
       return e.slice(0, -t.length);
     }
@@ -502,7 +542,7 @@ function stripSuffix(e) {
 async function runExportCli(e) {
   if (parseHelp(e)) {
     !function printExportHelp() {
-      process.stdout.write([ "Usage: 2g export [selector]", "", "Exports session events to Chrome Trace or OTLP JSON.", "", "Options:", "  selector                 Substring of PID, CWD, or command; a running", "                           session wins ties", "  --input <file>           Read JSONL events from a file", "  -o, --output <file>      Write output to a file", "  --format <format>        chrome-trace or opentelemetry", "  --json                   Print JSON output", "  --since <time>           Duration ago (5m, 90s), Unix time, or ISO date", "  --filter <pattern>       Event name prefix (whole segments), e.g. category,", "                           category:kind; * wildcards; comma-separated", "  --spans                  Keep only span events (log.span() pairs with a _d", "                           duration); omit to include point events too. A", '                           plain "ms" payload field is not a span', "  --debug                  Include debug events (only recorded when the", "                           command ran with LOG_DEBUG set)", "  --tail                   Follow live events after replaying history", "  --timeout <duration>     Stop tailing after an absolute duration", "                           Tail also stops after 30s without new events", "" ].join("\n"));
+      process.stdout.write([ "Usage: 2g export [selector]", "", "Exports session events to Chrome Trace or OTLP JSON.", "(Without --tail it reads only the retained window. Rotated out logs may be lost)", "", "--tail attaches to an already-running session and follows live from that point.", "  Run it after the session is up and leave it attached while the workload runs.", "  It will automatically stop on 30s idle.", "To trace a full command instead, use `2g record`.", "", "Options:", "  selector                 Substring of PID, CWD, or command; a running", "                           session wins ties", "  --input <file>           Read JSONL events from a file", "  -o, --output <file>      Write output to a file", "  --format <format>        chrome-trace or opentelemetry", "  --json                   Print JSON output", "  --since <time>           Duration ago (5m, 90s), Unix time, or ISO date", "  --filter <pattern>       Event name prefix (whole segments), e.g. category,", "                           category:kind; * wildcards; comma-separated", "  --spans                  Keep only span events (log.span() pairs with a _d", "                           duration); omit to include point events too. A", '                           plain "ms" payload field is not a span', "  --debug                  Include debug events (only recorded when the", "                           command ran with LOG_DEBUG set)", "  --tail                   Follow live events after replaying history; stops", "                           automatically on 30s idle", "  --timeout <duration>     Also stop tailing after this absolute duration", "" ].join("\n"));
     }();
     return;
   }
@@ -511,7 +551,7 @@ async function runExportCli(e) {
       args: e,
       allowPositionals: !0,
       options: {
-        ...c,
+        ...p,
         input: {
           type: "string"
         },
@@ -546,7 +586,7 @@ async function runExportCli(e) {
       return t;
     }(s.values.timeout);
     const i = s.values.format ?? "chrome-trace";
-    if (!function isExportFormat(e) {
+    if (!function isExportFormat$1(e) {
       return "chrome-trace" === e || "opentelemetry" === e;
     }(i)) {
       throw new Error(`Unsupported format: ${i}`);
@@ -577,13 +617,14 @@ async function runExportCli(e) {
   }
   let a;
   let l;
-  let p;
+  let c;
   if (i.selector) {
     const e = await r.resolveSession(i.selector);
     l = function formatSessionProcessName(e) {
       return e.version ? `${e.command} (v${e.version}, PID ${e.pid})` : `${e.command} (PID ${e.pid})`;
     }(e);
-    p = e.pid;
+    c = e.pid;
+    await warnOnRotationLoss(e.sessionDir, "2g export --tail");
     a = r.tap(e.sessionDir, {
       follow: i.follow,
       debug: i.debug,
@@ -601,37 +642,12 @@ async function runExportCli(e) {
       yield* readJsonlStream(process.stdin);
     }();
   }
-  const u = async function* filterEvents(e, t) {
-    const s = n.compileEventFilter(t.filter);
-    const o = n.parseSince(t.since);
-    for await (const r of e) {
-      if (n.matchesTapOptions(r, {
-        filter: t.filter,
-        since: o,
-        spans: t.spans,
-        debug: t.debug
-      }, s)) {
-        yield r;
-      }
-    }
-  }(a, i);
-  const d = "opentelemetry" === i.format ? await async function convertToOpenTelemetry(e, t = {}) {
-    const n = new OpenTelemetryConverter(t);
-    for await (const t of e) {
-      n.add(t);
-    }
-    return n.toFile();
-  }(u, {
-    pid: p,
+  const u = filterEvents(a, i);
+  const d = "opentelemetry" === i.format ? await convertToOpenTelemetry(u, {
+    pid: c,
     processName: l
-  }) : await async function convertToChromeTrace(e, t = {}) {
-    const n = new TraceConverter(t);
-    for await (const t of e) {
-      n.add(t);
-    }
-    return n.toTraceFile();
-  }(u, {
-    pid: p,
+  }) : await convertToChromeTrace(u, {
+    pid: c,
     processName: l
   });
   const f = JSON.stringify(d, null, 2);
@@ -646,6 +662,99 @@ function escapeTsv(e) {
   return String(e).replace(/\\/g, "\\\\").replace(/\t/g, "\\t").replace(/\r/g, "\\r").replace(/\n/g, "\\n");
 }
 
+async function runRecordCli(e) {
+  if (parseHelp(e)) {
+    !function printRecordHelp() {
+      process.stdout.write([ "Usage: 2g record [options] -- <command> [args...]", "", "Runs <command>, traces the events it emits, and writes the trace on exit.", "", "This is the reliable way to capture a one-off run (a build, a script): 2g", "owns the process, so the trace is complete end-to-end with no window to", "attach within and nothing to rotate out. To trace an already-running server", "instead, use `2g export <selector> --tail`.", "", "Options:", "  -o, --output <file>      Write the trace to a file (default: stdout)", "  --format <format>        chrome-trace or opentelemetry", "  --json                   Print JSON output", "  --filter <pattern>       Event name prefix (whole segments), e.g. category,", "                           category:kind; * wildcards; comma-separated", "  --spans                  Keep only span events (log.span() pairs with a _d", "                           duration); omit to include point events too", "  --debug                  Enable and export debug events; no LOG_DEBUG needed", "", "Example:", "  2g record -o trace.json -- expo export   # run & trace a build end-to-end", "" ].join("\n"));
+    }();
+    return;
+  }
+  const n = e.indexOf("--");
+  const i = -1 === n ? e : e.slice(0, n);
+  const a = -1 === n ? [] : e.slice(n + 1);
+  const c = function parseRecordOptions(e) {
+    const n = t.parseArgs({
+      args: e,
+      allowPositionals: !0,
+      options: {
+        filter: {
+          type: "string",
+          multiple: !0
+        },
+        spans: {
+          type: "boolean"
+        },
+        debug: {
+          type: "boolean"
+        },
+        output: {
+          type: "string",
+          short: "o"
+        },
+        format: {
+          type: "string"
+        },
+        json: {
+          type: "boolean"
+        },
+        help: {
+          type: "boolean",
+          short: "h"
+        }
+      }
+    });
+    const s = n.values.format ?? "chrome-trace";
+    if (!function isExportFormat(e) {
+      return "chrome-trace" === e || "opentelemetry" === e;
+    }(s)) {
+      throw new Error(`Unsupported format: ${s}`);
+    }
+    return {
+      output: n.values.output,
+      format: s,
+      filter: n.values.filter?.flatMap(e => e.split(",")).map(e => e.trim()).filter(Boolean),
+      spans: !0 === n.values.spans,
+      debug: !0 === n.values.debug,
+      json: n.values.json ?? !1
+    };
+  }(i);
+  if (!a.length) {
+    throw new Error("record needs a command to run: 2g record [options] -- <command> [args...]");
+  }
+  if (c.json) {
+    s.redirectConsoleToStderr();
+  }
+  const p = r.captureEvents({
+    debug: c.debug,
+    filter: c.filter
+  });
+  const u = l.spawn(a[0], a.slice(1), p.spawnOptions({
+    env: process.env,
+    stdio: [ "inherit", c.output ? "inherit" : 2, "inherit" ]
+  }));
+  p.attach(u);
+  const d = new Promise((e, t) => {
+    u.on("exit", t => e(t ?? 0));
+    u.on("error", e => t(new Error(`Failed to run ${a[0]}: ${e.message}`)));
+  });
+  const f = {
+    pid: u.pid,
+    processName: a.join(" ")
+  };
+  const m = filterEvents(p, c);
+  const h = "opentelemetry" === c.format ? await convertToOpenTelemetry(m, f) : await convertToChromeTrace(m, f);
+  const g = await d;
+  const v = JSON.stringify(h, null, 2);
+  if (c.output) {
+    o.writeFileSync(c.output, `${v}\n`);
+  } else {
+    process.stdout.write(`${v}\n`);
+  }
+  if (g) {
+    process.exitCode = g;
+  }
+}
+
 async function runTapCli(e) {
   if (parseHelp(e)) {
     !function printTapHelp() {
@@ -658,7 +767,7 @@ async function runTapCli(e) {
       args: e,
       allowPositionals: !0,
       options: {
-        ...c,
+        ...p,
         format: {
           type: "string"
         },
@@ -690,6 +799,7 @@ async function runTapCli(e) {
     s.redirectConsoleToStderr();
   }
   const o = await r.resolveSession(n.selector);
+  await warnOnRotationLoss(o.sessionDir, "2g tap --tail");
   const i = s.shouldColorizeStream(process.stdout);
   for await (const e of r.tap(o.sessionDir, n)) {
     if (n.pretty) {
@@ -705,9 +815,9 @@ async function runTapCli(e) {
 
 async function main(e = process.argv.slice(2)) {
   const [n, ...o] = e;
-  if (!n || "--help" === n || "-h" === n) {
+  if (!n || "--help" === n || "-h" === n || "help" === n) {
     !function printHelp() {
-      process.stdout.write([ "Usage: 2g <command>", "", "Reads structured JSONL event logs that instrumented CLIs record during runs", "into the system temp dir, with no setup: run a command, then tap it here.", "", "Commands:", "  ps [selector]                 List recorded sessions", "    --active, -a (running only)  --json", "", "  tap [selector]                Replay session events as JSONL, oldest first", "    --since <time>  --filter <pattern>  --spans  --debug  --format pretty", "    --tail (follow live events after replay; runs until killed)", "", "  export [selector]             Export events to Chrome Trace or OTLP JSON", "    --input <jsonl-file>  -o, --output <file>  --json", "    --format chrome-trace|opentelemetry", "    --since <time>  --filter <pattern>  --spans  --debug", "    --tail  --timeout <duration> (absolute; tail also stops after 30s idle)", "", "  typegen                       List every event name/payload a project can emit", "    -p, --project <tsconfig>  -o, --output <file>  --format dts|json  --json", "", "  clean                         Remove stale sessions", "    --all, -a (remove all exited sessions)  --json", "", "Typical use:", "  2g ps -a                                         # what is running now?", '  2g tap "expo start" --tail                       # follow live events', '  2g tap "expo start" --since 5m --format pretty   # recent history, readable', '  2g tap "expo start" --filter metro:bundling      # narrow to one area', '  2g export "expo start" -o trace.json             # flame chart of a run', "", "Selectors match sessions by substring of PID, CWD, or command. If several", "match, and exactly one of them is running, it is chosen; otherwise 2g errors", "and lists the candidates.", "", "--filter takes comma-separated event-name prefixes matched on whole", 'segments: "category" and "category:kind" both match "category:kind:test";', "* matches anything. Discover names by tapping unfiltered or via typegen.", "", "--since accepts a duration ago (5m, 90s, 1h30m), Unix time, or ISO date.", '--spans keeps only span events (log.span() pairs with a "_d" duration in', "ms); without it, point events are included alongside spans.", "", 'Events are single JSON lines: {"_e":"category:kind","_t":<epoch ms>,...}.', '"_d" is a span duration, "_w" a worker id; debug events need --debug.', "", "Set LOG_EVENTS=<file|fd> on an instrumented command to redirect its events.", "Debug events are only recorded when the command runs with LOG_DEBUG set.", "", "Pass LOG_DEBUG=<filter> when debugging; it also mirrors matching events to", "stderr. Reading them back needs --debug.", "", "Run 2g <command> --help for per-command help.", "" ].join("\n"));
+      process.stdout.write([ "Usage: 2g <command>", "", "Reads structured JSONL event logs that instrumented CLIs record during runs", "into the system temp dir, with no setup: run a command, then tap it here.", "", "Commands:", "  ps [selector]                 List recorded sessions", "    --active, -a (running only)  --json", "", "  tap [selector]                Replay session events as JSONL, oldest first", "    --since <time>  --filter <pattern>  --spans  --debug  --format pretty", "    --tail (follow live events after replay; runs until killed)", "", "  record -- <command>          Run a command, trace it end-to-end, write on exit", "    -o, --output <file>  --format chrome-trace|opentelemetry  --json", "    --filter <pattern>  --spans  --debug", "", "  export [selector]             Export a past or live (--tail) session", "    --input <jsonl-file>  -o, --output <file>  --json", "    --format chrome-trace|opentelemetry", "    --since <time>  --filter <pattern>  --spans  --debug", "    --tail  --timeout <duration> (absolute; tail also stops after 30s idle)", "", "  typegen                       List every event name/payload a project can emit", "    -p, --project <tsconfig>  -o, --output <file>  --format dts|json  --json", "", "  clean                         Remove stale sessions", "    --all, -a (remove all exited sessions)  --json", "", "Typical use:", "  2g ps -a                                         # what is running now?", '  2g tap "expo start" --tail                       # follow live events', '  2g tap "expo start" --since 5m --format pretty   # recent history, readable', '  2g tap "expo start" --filter metro:bundling      # narrow to one area', "", "Trace a run to a flame chart:", "  2g record -o trace.json -- expo export           # run & trace a build", '  2g export "expo start" --tail -o trace.json      # attach to a running server', '  2g export "expo start" -o trace.json             # after the fact (partial)', "", "Selectors match sessions by substring of PID, CWD, or command. If several", "match, and exactly one of them is running, it is chosen; otherwise 2g errors", "and lists the candidates.", "", "--filter takes comma-separated event-name prefixes matched on whole", 'segments: "category" and "category:kind" both match "category:kind:test";', "* matches anything. Discover names by tapping unfiltered or via typegen.", "", "--since accepts a duration ago (5m, 90s, 1h30m), Unix time, or ISO date.", '--spans keeps only span events (log.span() pairs with a "_d" duration in', "ms); without it, point events are included alongside spans.", "", 'Events are single JSON lines: {"_e":"category:kind","_t":<epoch ms>,...}.', '"_d" is a span duration, "_w" a worker id; debug events need --debug.', "", "Set LOG_EVENTS=<file|fd> on an instrumented command to redirect its events.", "Debug events are only recorded when the command runs with LOG_DEBUG set.", "", "Pass LOG_DEBUG=<filter> when debugging; it also mirrors matching events to", "stderr. Reading them back needs --debug.", "", "Run 2g <command> --help for per-command help.", "" ].join("\n"));
     }();
     return 0;
   }
@@ -777,6 +887,10 @@ async function main(e = process.argv.slice(2)) {
     runCleanCli(o);
     return 0;
 
+   case "record":
+    await runRecordCli(o);
+    return 0;
+
    case "export":
     await runExportCli(o);
     return 0;
@@ -788,7 +902,7 @@ async function main(e = process.argv.slice(2)) {
 
 if (function isCliEntrypoint() {
   try {
-    return process.argv[1] === e.fileURLToPath("undefined" == typeof document ? require("url").pathToFileURL(__filename).href : l && "SCRIPT" === l.tagName.toUpperCase() && l.src || new URL("dist/chunks/cli-chunk.js", document.baseURI).href);
+    return process.argv[1] === e.fileURLToPath("undefined" == typeof document ? require("url").pathToFileURL(__filename).href : c && "SCRIPT" === c.tagName.toUpperCase() && c.src || new URL("dist/chunks/cli-chunk.js", document.baseURI).href);
   } catch {
     return !1;
   }