@mauroandre/velojs 0.0.58 → 0.0.59

package/dist/sockets.js

@@ -1,4 +1,5 @@
-async function* W(e) {
+import { trace as _, byteLength as M } from "./telemetry.js";
+async function* N(e) {
   for await (const t of e) {
     const n = typeof t == "string" ? t : new TextDecoder().decode(t);
     try {
@@ -8,28 +9,28 @@ async function* W(e) {
     }
   }
 }
-const g = /* @__PURE__ */ new WeakMap(), k = /* @__PURE__ */ new WeakMap(), S = /* @__PURE__ */ new WeakMap();
-async function p(e) {
-  let t = g.get(e);
+const S = /* @__PURE__ */ new WeakMap(), m = /* @__PURE__ */ new WeakMap(), w = /* @__PURE__ */ new WeakMap();
+async function x(e) {
+  let t = S.get(e);
   if (t) return t;
   try {
-    return t = (await import("@hono/node-ws")).createNodeWebSocket({ app: e }), g.set(e, t), t;
+    return t = (await import("@hono/node-ws")).createNodeWebSocket({ app: e }), S.set(e, t), t;
   } catch (n) {
     return console.error("[velojs] failed to load @hono/node-ws:", n), null;
   }
 }
 function b(e, t) {
-  let n = S.get(e);
-  n || (n = /* @__PURE__ */ new Set(), S.set(e, n)), n.add(t);
+  let n = w.get(e);
+  n || (n = /* @__PURE__ */ new Set(), w.set(e, n)), n.add(t);
 }
-function m(e, t) {
-  S.get(e)?.delete(t);
+function p(e, t) {
+  w.get(e)?.delete(t);
 }
-function _(e, t) {
-  return b(e, t), () => m(e, t);
+function $(e, t) {
+  return b(e, t), () => p(e, t);
 }
-function M(e) {
-  const t = S.get(e);
+function E(e) {
+  const t = w.get(e);
   if (t) {
     for (const n of t)
       try {
@@ -39,158 +40,170 @@ function M(e) {
     t.clear();
   }
 }
-function x(e) {
-  return k.get(e) ?? /* @__PURE__ */ new Map();
+function L(e) {
+  return m.get(e) ?? /* @__PURE__ */ new Map();
 }
-function j(e, t, n) {
-  const i = [];
-  let r = null, s = !1, c = !1, o = null;
-  const l = new AbortController();
-  b(e, l);
-  const u = {
+function I(e, t, n, u) {
+  const a = [];
+  let s = null, r = !1, i = !1, c = null;
+  const l = _("socket-connect", {
+    route: u.path,
+    module: u.moduleId,
+    name: u.name
+  });
+  let h = !1;
+  const d = (f) => {
+    h || (h = !0, l.end({ status: f }));
+  }, y = new AbortController();
+  b(e, y);
+  const k = {
     async *[Symbol.asyncIterator]() {
       for (; ; ) {
-        for (; i.length > 0; )
-          yield i.shift();
-        if (s) return;
+        for (; a.length > 0; )
+          yield a.shift();
+        if (r) return;
         await new Promise((f) => {
-          r = f;
-        }), r = null;
+          s = f;
+        }), s = null;
       }
     }
-  }, d = (f) => {
-    if (!(!o || s))
+  }, v = (f) => {
+    if (!(!c || r))
       try {
-        typeof f == "string" || f instanceof Uint8Array ? o.send(f) : o.send(JSON.stringify(f));
-      } catch (a) {
-        console.error("[velojs] socket send failed:", a);
+        const o = typeof f == "string" || f instanceof Uint8Array ? f : JSON.stringify(f);
+        c.send(o), l.enabled && l.delivery(typeof o == "string" ? M(o) : o.byteLength);
+      } catch (o) {
+        console.error("[velojs] socket send failed:", o);
       }
-  }, w = (f, a) => {
-    if (o)
+  }, j = (f, o) => {
+    if (c)
       try {
-        o.close(f, a);
+        c.close(f, o);
       } catch {
       }
-  }, y = () => {
-    c = !0;
-  }, h = () => {
-    if (s || (s = !0, r?.()), !l.signal.aborted)
+  }, A = () => {
+    i = !0, d("ok");
+  }, g = () => {
+    if (r || (r = !0, s?.(), l.close()), !y.signal.aborted)
       try {
-        l.abort();
+        y.abort();
       } catch {
       }
-    m(e, l);
+    p(e, y);
   };
   return {
     events: {
-      onOpen(f, a) {
-        o = a, Promise.resolve(
+      onOpen(f, o) {
+        c = o, Promise.resolve(
           t({
-            incoming: u,
-            send: d,
-            close: w,
-            keepOpen: y,
-            abortSignal: l.signal,
+            incoming: k,
+            send: v,
+            close: j,
+            keepOpen: A,
+            abortSignal: y.signal,
             c: n,
             params: n.req.param(),
             query: n.req.query()
           })
         ).then(() => {
-          if (!c && o && !s)
+          if (d("ok"), !i && c && !r)
             try {
-              o.close();
+              c.close();
             } catch {
             }
-        }).catch((v) => {
-          console.error("[velojs] socket handler threw:", v);
+        }).catch((W) => {
+          d("error"), console.error("[velojs] socket handler threw:", W);
           try {
-            o?.close(1011, "handler error");
+            c?.close(1011, "handler error");
           } catch {
           }
-        });
+        }), typeof setImmediate == "function" ? setImmediate(() => d("ok")) : setTimeout(() => d("ok"), 0);
       },
       onMessage(f) {
-        if (s) return;
-        const a = f.data;
-        typeof a == "string" ? i.push(a) : a instanceof ArrayBuffer ? i.push(new Uint8Array(a)) : a && typeof a == "object" && "buffer" in a && a.buffer instanceof ArrayBuffer && i.push(new Uint8Array(a.buffer)), r?.();
+        if (r) return;
+        const o = f.data;
+        typeof o == "string" ? a.push(o) : o instanceof ArrayBuffer ? a.push(new Uint8Array(o)) : o && typeof o == "object" && "buffer" in o && o.buffer instanceof ArrayBuffer && a.push(new Uint8Array(o.buffer)), s?.();
       },
       onClose() {
-        h();
+        g();
       },
       onError() {
-        h();
+        g();
       }
     },
-    cleanup: h
+    cleanup: g
   };
 }
-async function A(e, t, n, i = []) {
-  let r = k.get(e);
-  r || (r = /* @__PURE__ */ new Map(), k.set(e, r)), r.set(t, { path: t, handler: n, middlewares: i });
-  const s = await p(e);
-  if (!s) return;
-  const c = s.upgradeWebSocket((o) => j(e, n, o).events);
-  i.length > 0 ? e.on(["GET"], [t], ...i, c) : e.on(["GET"], [t], c);
+async function O(e, t, n, u = [], a = {}) {
+  let s = m.get(e);
+  s || (s = /* @__PURE__ */ new Map(), m.set(e, s)), s.set(t, { path: t, handler: n, middlewares: u });
+  const r = await x(e);
+  if (!r) return;
+  const i = r.upgradeWebSocket((c) => I(e, n, c, { path: t, ...a }).events);
+  u.length > 0 ? e.on(["GET"], [t], ...u, i) : e.on(["GET"], [t], i);
 }
-async function O(e, t, n = []) {
-  const i = async (r, s) => {
-    for (const c of r) {
-      const o = c.module?.metadata?.moduleId, l = [...s, ...c.middlewares ?? []];
-      if (c.module && o)
-        for (const u of Object.keys(c.module)) {
-          if (!u.startsWith("socket_")) continue;
-          const d = c.module[u];
-          if (typeof d != "function") {
+async function R(e, t, n = []) {
+  const u = async (a, s) => {
+    for (const r of a) {
+      const i = r.module?.metadata?.moduleId, c = [...s, ...r.middlewares ?? []];
+      if (r.module && i)
+        for (const l of Object.keys(r.module)) {
+          if (!l.startsWith("socket_")) continue;
+          const h = r.module[l];
+          if (typeof h != "function") {
             console.warn(
-              `[velojs] socket_* export ${o}/${u} is not a function; skipped`
+              `[velojs] socket_* export ${i}/${l} is not a function; skipped`
             );
             continue;
           }
-          const w = u.replace("socket_", ""), y = `/_socket/${o}/${w}`;
+          const d = l.replace("socket_", ""), y = `/_socket/${i}/${d}`;
           try {
-            d.__path = y;
+            h.__path = y;
           } catch {
           }
           try {
-            d.__isVeloSocket = !0;
+            h.__isVeloSocket = !0;
           } catch {
           }
-          await A(e, y, d, l);
+          await O(e, y, h, c, {
+            moduleId: i,
+            name: d
+          });
         }
-      c.children && await i(c.children, l);
+      r.children && await u(r.children, c);
     }
   };
-  await i(t, n);
+  await u(t, n);
 }
-async function J(e, t) {
-  const n = g.get(e);
+async function T(e, t) {
+  const n = S.get(e);
   if (!n) return;
-  const i = new Proxy(t, {
-    get(r, s, c) {
-      return s === "on" || s === "addListener" ? (o, l) => o !== "upgrade" ? r[s](o, l) : r[s]("upgrade", (u, d, w) => {
-        const y = u.headers?.host ?? "localhost";
-        let h;
+  const u = new Proxy(t, {
+    get(a, s, r) {
+      return s === "on" || s === "addListener" ? (i, c) => i !== "upgrade" ? a[s](i, c) : a[s]("upgrade", (l, h, d) => {
+        const y = l.headers?.host ?? "localhost";
+        let k;
         try {
-          h = new URL(u.url ?? "/", `http://${y}`).pathname;
+          k = new URL(l.url ?? "/", `http://${y}`).pathname;
         } catch {
           return;
         }
-        k.get(e)?.has(h) && l(u, d, w);
-      }) : Reflect.get(r, s, c);
+        m.get(e)?.has(k) && c(l, h, d);
+      }) : Reflect.get(a, s, r);
     }
   });
   try {
-    n.injectWebSocket(i);
-  } catch (r) {
-    console.error("[velojs] injectWebSocket failed:", r);
+    n.injectWebSocket(u);
+  } catch (a) {
+    console.error("[velojs] injectWebSocket failed:", a);
   }
 }
 export {
-  M as abortAllSocketSessions,
-  x as getAppSockets,
-  J as injectWebSocketServer,
-  W as parseJson,
-  A as registerSocketHandler,
-  O as registerSocketRoutes,
-  _ as trackSocketSession
+  E as abortAllSocketSessions,
+  L as getAppSockets,
+  T as injectWebSocketServer,
+  N as parseJson,
+  O as registerSocketHandler,
+  R as registerSocketRoutes,
+  $ as trackSocketSession
 };

package/dist/telemetry-cli.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `velojs telemetry` — the inaugural consumption surface over the collection.
+ *
+ * Reads the JSONL the runtime writes (one line per trace) and prints the
+ * ranking by route/action/channel — count, errors, p50/p95 and volume in bytes
+ * — plus the timeline. The window is the whole file by default, recut with
+ * `--last <duration>` (`--last 60m`). Without a path, the destination comes
+ * from `VELO_TELEMETRY_FILE` in the environment or in the project's `.env`,
+ * including the instance and rotation files that derive from it; an explicit
+ * path reads a JSONL copied from production.
+ *
+ * No UI, no server route: the operator's terminal is the whole surface.
+ */
+import { type TelemetryEvent } from "./telemetry.js";
+export interface TelemetryCliIo {
+    cwd?: string | undefined;
+    env?: Record<string, string | undefined> | undefined;
+    write?: ((line: string) => void) | undefined;
+    writeError?: ((line: string) => void) | undefined;
+}
+export interface RankRow {
+    key: string;
+    count: number;
+    errors: number;
+    p50: number | null;
+    p95: number | null;
+    bytes: number;
+}
+export interface TimelineEntry {
+    ts: string;
+    type: string;
+    label: string;
+    duration: number | null;
+    status: string | null;
+    bytes: number | null;
+    deliveries: number | null;
+}
+export interface TelemetryReport {
+    files: string[];
+    events: TelemetryEvent[];
+    routes: RankRow[];
+    actions: RankRow[];
+    channels: RankRow[];
+    timeline: TimelineEntry[];
+}
+/** `--last` accepts `ms`, `s`, `m`, `h`, `d`; a bare number counts seconds. */
+export declare function parseDuration(raw: string): number;
+/**
+ * The files a destination resolves to. The effective file of each instance
+ * carries a pid/hostname suffix (`telemetry.123-host.jsonl`) and rotation adds
+ * a numeric tail (`…jsonl.1`), so a base path collects its whole family. A
+ * directory collects every JSONL inside it.
+ */
+export declare function collectTelemetryFiles(target: string, basePath: boolean): string[];
+/** Reads every JSONL file, skipping malformed lines, in chronological order. */
+export declare function readTelemetryEvents(files: string[]): TelemetryEvent[];
+/** Keeps the events inside the `--last` window (everything without `lastMs`). */
+export declare function windowEvents(events: TelemetryEvent[], lastMs: number | null, nowMs: number): TelemetryEvent[];
+/** The whole analysis, as data: rankings + timeline. */
+export declare function buildTelemetryReport(files: string[], events: TelemetryEvent[]): TelemetryReport;
+/** Renders the human report — the CLI's whole stdout. */
+export declare function formatTelemetryReport(report: TelemetryReport, lastMs: number | null, nowMs: number, lastLabel?: string): string;
+/**
+ * Runs the `telemetry` command. Throws (legibly) on a missing destination;
+ * the CLI turns that into exit code 1.
+ */
+export declare function runTelemetryCli(args: string[], io?: TelemetryCliIo): Promise<void>;

package/dist/telemetry-cli.js

@@ -0,0 +1,265 @@
+import d from "node:fs";
+import a from "node:path";
+import { expandTelemetryValue as w } from "./telemetry.js";
+import { readProjectEnv as k } from "./telemetry-node.js";
+function j(e) {
+  const o = e.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/);
+  if (!o)
+    throw new Error(
+      `[velojs] invalid duration "${e}" — use a unit: 500ms, 30s, 60m, 2h, 7d.`
+    );
+  const n = Number(o[1]), i = o[2] ?? "s";
+  return n * (i === "ms" ? 1 : i === "s" ? 1e3 : i === "m" ? 6e4 : i === "h" ? 36e5 : 864e5);
+}
+function g(e) {
+  try {
+    return d.statSync(e);
+  } catch {
+    return null;
+  }
+}
+function x(e, o) {
+  const n = g(e);
+  if (n?.isDirectory())
+    return d.readdirSync(e).filter((u) => u.includes(".jsonl")).sort().map((u) => a.join(e, u));
+  if (n?.isFile()) return [e];
+  if (!o)
+    throw new Error(`[velojs] velojs telemetry: file not found — ${e}`);
+  const i = a.dirname(e), t = a.basename(e), r = t.lastIndexOf("."), s = r > 0 ? t.slice(0, r) : t, l = r > 0 ? t.slice(r) : "";
+  if (!g(i))
+    throw new Error(
+      `[velojs] velojs telemetry: no telemetry files at ${e} — the directory does not exist.`
+    );
+  const h = d.readdirSync(i).filter((u) => u === t ? !0 : u.startsWith(`${s}.`) ? l === "" || u.includes(l) : !1).sort().map((u) => a.join(i, u));
+  if (h.length === 0)
+    throw new Error(
+      `[velojs] velojs telemetry: no telemetry files found for ${e} — set VELO_TELEMETRY_FILE (see .env.example) or pass the JSONL path explicitly.`
+    );
+  return h;
+}
+function M(e, o, n, i) {
+  if (e) {
+    const l = w(e, { ...n, ...o }), h = a.isAbsolute(l) ? l : a.resolve(i, l);
+    return x(h, !1);
+  }
+  const t = o.VELO_TELEMETRY_FILE ?? n.VELO_TELEMETRY_FILE ?? "";
+  if (!t.trim())
+    throw new Error(
+      "[velojs] velojs telemetry: no destination — set VELO_TELEMETRY_FILE in the environment or in the project's .env (see .env.example), or pass the JSONL path as an argument."
+    );
+  const r = w(t.trim(), { ...n, ...o }), s = a.isAbsolute(r) ? r : a.resolve(i, r);
+  return x(s, !0);
+}
+function O(e) {
+  const o = [];
+  for (const n of e) {
+    let i;
+    try {
+      i = d.readFileSync(n, "utf-8");
+    } catch (t) {
+      throw new Error(
+        `[velojs] velojs telemetry: cannot read ${n} — ${t instanceof Error ? t.message : String(t)}`
+      );
+    }
+    for (const t of i.split(`
+`)) {
+      const r = t.trim();
+      if (r)
+        try {
+          const s = JSON.parse(r);
+          s && typeof s == "object" && typeof s.type == "string" && o.push(s);
+        } catch {
+        }
+    }
+  }
+  return o.sort((n, i) => {
+    const t = Date.parse(n.ts ?? ""), r = Date.parse(i.ts ?? "");
+    return (Number.isFinite(t) ? t : 0) - (Number.isFinite(r) ? r : 0);
+  }), o;
+}
+function N(e, o, n) {
+  if (o === null) return e;
+  const i = n - o;
+  return e.filter((t) => {
+    const r = Date.parse(t.ts ?? "");
+    return Number.isFinite(r) && r >= i;
+  });
+}
+function L(e, o) {
+  if (e.length === 0) return null;
+  const n = [...e].sort((s, l) => s - l);
+  if (n.length === 1) return n[0];
+  const i = (n.length - 1) * o, t = Math.floor(i), r = Math.ceil(i);
+  return t === r ? n[t] : n[t] + (n[r] - n[t]) * (i - t);
+}
+function y(e, o, n) {
+  const i = /* @__PURE__ */ new Map();
+  for (const t of e) {
+    if (!o(t)) continue;
+    const r = n(t);
+    let s = i.get(r);
+    s || (s = { durations: [], count: 0, errors: 0, bytes: 0 }, i.set(r, s)), s.count += 1, t.status === "error" && (s.errors += 1), typeof t.duration == "number" && Number.isFinite(t.duration) && s.durations.push(t.duration), typeof t.bytes == "number" && Number.isFinite(t.bytes) && (s.bytes += t.bytes);
+  }
+  return [...i.entries()].map(([t, r]) => ({
+    key: t,
+    count: r.count,
+    errors: r.errors,
+    p50: L(r.durations, 0.5),
+    p95: L(r.durations, 0.95),
+    bytes: r.bytes
+  })).sort((t, r) => r.count - t.count || (t.key < r.key ? -1 : t.key > r.key ? 1 : 0));
+}
+const R = (e) => e.type === "page" || e.type === "data" || e.type === "endpoint", D = (e) => {
+  const o = e.route ?? "(no route)";
+  return e.type === "endpoint" && e.method ? `${e.method} ${o}` : o;
+}, S = (e) => `${e.module ?? "(no module)"}/${e.name ?? "(no name)"}`, _ = (e) => typeof e.channel == "string";
+function B(e) {
+  switch (e.type) {
+    case "page":
+    case "data":
+    case "endpoint":
+      return `${e.method ? `${e.method} ` : ""}${e.route ?? "(no route)"}`;
+    case "action":
+      return S(e);
+    case "emit":
+      return `${e.channel ?? "?"} (${e.mode ?? "?"}${e.connections !== void 0 ? `, ${e.connections} conn` : ""})`;
+    case "delivery":
+      return `${e.channel ?? "?"} #${e.deliveries ?? "?"}`;
+    case "close":
+      return `${e.channel ?? "?"} ${e.deliveries ?? 0} deliveries`;
+    case "stream-connect":
+      return `${e.route ?? "?"}${e.channel ? ` [${e.channel}]` : ""}`;
+    case "socket-connect":
+      return e.route ?? "?";
+    case "channel-connect":
+      return `${e.channel ?? "?"} [${e.module ?? "?"}]`;
+    case "boot":
+      return `version ${e.version ?? "?"} env ${e.env ?? "?"}`;
+    default:
+      return e.route ?? e.channel ?? "?";
+  }
+}
+function I(e, o) {
+  return {
+    files: e,
+    events: o,
+    routes: y(o, R, D),
+    actions: y(o, (n) => n.type === "action", S),
+    channels: y(o, _, (n) => n.channel),
+    timeline: o.map((n) => ({
+      ts: n.ts ?? "",
+      type: n.type,
+      label: B(n),
+      duration: typeof n.duration == "number" ? n.duration : null,
+      status: n.status ?? null,
+      bytes: typeof n.bytes == "number" ? n.bytes : null,
+      deliveries: typeof n.deliveries == "number" ? n.deliveries : null
+    }))
+  };
+}
+const V = "—";
+function p(e) {
+  return e === null ? V : e >= 1e3 ? `${(e / 1e3).toFixed(2)}s` : `${e.toFixed(1)}ms`;
+}
+function E(e) {
+  return e <= 0 ? "0" : e >= 1024 * 1024 ? `${(e / (1024 * 1024)).toFixed(1)}MB` : e >= 1024 ? `${(e / 1024).toFixed(1)}KB` : `${e}B`;
+}
+function $(e, o) {
+  const n = [e];
+  if (o.length === 0)
+    return n.push("  (nothing)"), n;
+  const i = {
+    key: Math.max(3, ...o.map((s) => s.key.length)),
+    count: Math.max(5, ...o.map((s) => String(s.count).length)),
+    errors: Math.max(6, ...o.map((s) => String(s.errors).length)),
+    p50: Math.max(4, ...o.map((s) => p(s.p50).length)),
+    p95: Math.max(4, ...o.map((s) => p(s.p95).length)),
+    bytes: Math.max(5, ...o.map((s) => E(s.bytes).length))
+  }, t = (s, l) => s.padEnd(l), r = (s, l) => s.padStart(l);
+  n.push(
+    `  ${t("key", i.key)}  ${r("count", i.count)}  ${r("errors", i.errors)}  ${r("p50", i.p50)}  ${r("p95", i.p95)}  ${r("bytes", i.bytes)}`
+  );
+  for (const s of o)
+    n.push(
+      `  ${t(s.key, i.key)}  ${r(String(s.count), i.count)}  ${r(String(s.errors), i.errors)}  ${r(p(s.p50), i.p50)}  ${r(p(s.p95), i.p95)}  ${r(E(s.bytes), i.bytes)}`
+    );
+  return n;
+}
+function J(e) {
+  const o = ["Timeline"];
+  if (e.length === 0)
+    return o.push("  (nothing)"), o;
+  for (const n of e) {
+    const i = n.ts.replace("T", " ").replace("Z", ""), t = n.duration === null ? "" : `  ${p(n.duration)}`, r = n.status ? `  ${n.status}` : "", s = n.bytes === null ? "" : `  ${E(n.bytes)}`;
+    o.push(`  ${i}  ${n.type.padEnd(15)}  ${n.label}${t}${r}${s}`);
+  }
+  return o;
+}
+function v(e, o, n, i) {
+  const t = ["VeloJS telemetry"];
+  t.push(`files:  ${e.files.length}`);
+  for (const s of e.files) t.push(`  ${s}`);
+  const r = o === null ? "the whole file" : `last ${i ?? W(o)} — since ${new Date(n - o).toISOString()}`;
+  return t.push(`window: ${r}`), t.push(`events: ${e.events.length}`), t.push(""), t.push(...$("By route", e.routes)), t.push(""), t.push(...$("By action", e.actions)), t.push(""), t.push(...$("By channel", e.channels)), t.push(""), t.push(...J(e.timeline)), t.join(`
+`);
+}
+function W(e) {
+  return e % 864e5 === 0 ? `${e / 864e5}d` : e % 36e5 === 0 ? `${e / 36e5}h` : e % 6e4 === 0 ? `${e / 6e4}m` : e % 1e3 === 0 ? `${e / 1e3}s` : `${e}ms`;
+}
+const b = `Usage: velojs telemetry [path] [--last <duration>]
+
+Ranks the JSONL written by the native telemetry (count, errors, p50/p95,
+bytes) by route, action and channel, and prints the timeline.
+
+  path            JSONL file copied from production (or a directory of them).
+                  Without it, VELO_TELEMETRY_FILE from the environment or the
+                  project's .env is used, including the instance/rotation
+                  files derived from it.
+  --last <dur>    Window: 500ms, 30s, 60m, 2h, 7d (default: the whole file).
+
+Examples:
+  velojs telemetry
+  velojs telemetry --last 60m
+  velojs telemetry ./telemetry.prod.jsonl`;
+async function U(e, o = {}) {
+  const n = o.cwd ?? process.cwd(), i = o.env ?? process.env, t = o.write ?? ((f) => console.log(f));
+  let r = null, s = null, l;
+  for (let f = 0; f < e.length; f += 1) {
+    const c = e[f];
+    if (c === "--help" || c === "-h") {
+      t(b);
+      return;
+    }
+    if (c === "--last") {
+      const m = e[f + 1];
+      if (m === void 0)
+        throw new Error("[velojs] velojs telemetry: --last requires a duration (e.g. --last 60m).");
+      s = j(m), l = m, f += 1;
+      continue;
+    }
+    if (c.startsWith("--last=")) {
+      l = c.slice(7), s = j(l);
+      continue;
+    }
+    if (c.startsWith("-"))
+      throw new Error(`[velojs] velojs telemetry: unknown flag "${c}".
+
+${b}`);
+    if (r !== null)
+      throw new Error(`[velojs] velojs telemetry: unexpected argument "${c}".
+
+${b}`);
+    r = c;
+  }
+  const h = k(n), u = M(r, i, h, n), T = N(O(u), s, Date.now()), F = I(u, T);
+  t(v(F, s, Date.now(), l));
+}
+export {
+  I as buildTelemetryReport,
+  x as collectTelemetryFiles,
+  v as formatTelemetryReport,
+  j as parseDuration,
+  O as readTelemetryEvents,
+  U as runTelemetryCli,
+  N as windowEvents
+};

package/dist/telemetry-node.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Native telemetry — the Node adapter.
+ *
+ * The client-safe core (`telemetry.ts`) holds the event model, the trace API
+ * and the destination resolution; this module owns everything that touches the
+ * filesystem, the host and the network: the append-only JSONL writer with
+ * size-based rotation and the instance suffix, the optional HTTP sink, the
+ * reading of the project's `.env` and of the app version for the boot record.
+ *
+ * Only server-side entry points import it (`server.tsx`, `telemetry-cli.ts`),
+ * which is what keeps the Node builtins out of the client bundle.
+ */
+import { type TelemetryWriter, type TelemetryWriterInput } from "./telemetry.js";
+/**
+ * Reads the project's `.env` — the runtime fallback for the destination envs,
+ * and the source the CLI resolves a missing `VELO_TELEMETRY_FILE` from.
+ * Missing or unreadable file → empty map; the process environment always wins.
+ */
+export declare function readProjectEnv(cwd?: string): Record<string, string>;
+/** `pid.hostname`, sanitized for a filename — one file per process replica. */
+export declare function nodeInstanceLabel(): string;
+/** The version of the app served — the project's `package.json`. */
+export declare function readAppVersion(cwd?: string): string | null;
+/**
+ * Builds the destination writer: append-only JSONL with size-based rotation,
+ * plus an optional HTTP POST per event. Failures are logged and never
+ * propagate — a telemetry destination down must not affect the request that
+ * produced the event.
+ */
+export declare function nodeTelemetryWriter(input: TelemetryWriterInput): Promise<TelemetryWriter>;
+/**
+ * Starts the collection with the Node adapter: process env plus the project's
+ * `.env`, the pid/hostname suffix, the app version for the boot record. This
+ * is what `createApp` calls; without a destination it is a no-op.
+ */
+export declare function initNodeTelemetry(opts?: {
+    instanceLabel?: string;
+}): Promise<void>;