rosession 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# rosession
 
-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.
+[RoSession](https://rosession.com) analytics for your Roblox games, in the terminal and for AI agents that run commands (Claude Code, Codex, Cursor).
+
+```bash
+npx rosession login                         # sign in with Roblox in your browser
+npx rosession games                         # your games
+npx rosession overview "My Game" --range 30d
+npx rosession leaving "My Game"             # why players leave
+npx rosession watch "My Game"               # live players, refreshes every 10 s
+npx rosession tools                         # every command and its options
+```
+
+Pretty in a terminal, JSON when a program runs it (or with `--json`). No browser? Make a token at
+rosession.com/dashboard/agents and run `npx rosession login --token rsa_…`, or set `ROSESSION_TOKEN`.
+
+Every reply has `status`, `data`, a `link` to the dashboard page, and `next`: commands worth running after it.

package/bin/rosession.mjs

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+// rosession: RoSession analytics in the terminal and for AI agents that run commands.
+//   rosession login [--token rsa_…]      sign in (browser, or paste a token)
+//   rosession <tool> [game] [--option value …] [--json]
+//   rosession watch [game]               live players, refreshed every 10 s
+// Pretty when a person runs it, JSON when a program does (stdout isn't a terminal) or with --json.
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const VERSION = "1.1.0";
+const DEFAULT_URL = "https://rosession.com";
+
+// ---------------------------------------------------------------- args
+const argv = process.argv.slice(2);
+const flags = {};
+const words = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith("--")) {
+    const [k, v] = a.slice(2).split("=", 2);
+    if (v !== undefined) flags[k] = v;
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) flags[k] = argv[++i];
+    else flags[k] = true;
+  } else if (a === "-h") flags.help = true;
+  else words.push(a);
+}
+const asJson = !!flags.json || !process.stdout.isTTY;
+const tty = process.stdout.isTTY && !flags.json && !process.env.NO_COLOR;
+
+// ---------------------------------------------------------------- config
+const configFile = join(process.env.XDG_CONFIG_HOME || (process.platform === "win32" ? process.env.APPDATA || homedir() : join(homedir(), ".config")), "rosession", "config.json");
+const readConfig = () => {
+  try {
+    return JSON.parse(readFileSync(configFile, "utf8"));
+  } catch {
+    return {};
+  }
+};
+const saveConfig = (c) => {
+  mkdirSync(dirname(configFile), { recursive: true });
+  writeFileSync(configFile, JSON.stringify(c, null, 2), { mode: 0o600 });
+};
+const config = readConfig();
+const base = String(flags.url || process.env.ROSESSION_URL || config.url || DEFAULT_URL).replace(/\/$/, "");
+let token = process.env.ROSESSION_TOKEN || config.token || "";
+
+// ---------------------------------------------------------------- output
+const c = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = c(1);
+const dim = c(2);
+const green = c(32);
+const red = c(31);
+const cyan = c(36);
+const violet = c("38;5;141");
+const nf = new Intl.NumberFormat("en-US");
+const num = (v, d = 0) => (v == null ? "–" : nf.format(Math.round(v * 10 ** d) / 10 ** d));
+const dur = (s) => (s == null ? "–" : s < 60 ? `${Math.round(s)}s` : s < 3600 ? `${Math.floor(s / 60)}m ${String(Math.round(s % 60)).padStart(2, "0")}s` : `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`);
+const pct = (v) => (v == null ? "–" : `${num(v, 1)}%`);
+const delta = (v, invert) => (v == null ? "" : (v >= 0) !== !!invert ? green(` ▲ ${num(Math.abs(v), 1)}%`) : red(` ▼ ${num(Math.abs(v), 1)}%`));
+const ago = (iso) => {
+  if (!iso) return "never";
+  const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  return s < 120 ? "just now" : s < 3600 ? `${Math.floor(s / 60)}m ago` : s < 86400 ? `${Math.floor(s / 3600)}h ago` : `${Math.floor(s / 86400)}d ago`;
+};
+const SPARK = "▁▂▃▄▅▆▇█";
+const spark = (vals) => {
+  const v = vals.map(Number).filter(Number.isFinite);
+  if (!v.length) return "";
+  const lo = Math.min(...v);
+  const hi = Math.max(...v);
+  return v.map((x) => SPARK[hi === lo ? 3 : Math.round(((x - lo) / (hi - lo)) * 7)]).join("");
+};
+const bar = (share, width = 20) => {
+  const fill = Math.min(width, Math.max(share > 0 ? 1 : 0, Math.round((share / 100) * width)));
+  return violet("█".repeat(fill)) + dim("·".repeat(width - fill));
+};
+const pad = (s, n) => {
+  const len = String(s).replace(/\x1b\[[0-9;]*m/g, "").length;
+  return String(s) + " ".repeat(Math.max(0, n - len));
+};
+function table(rows, cols) {
+  const widths = cols.map((col) => Math.max(col.label.length, ...rows.map((r) => String(col.get(r)).replace(/\x1b\[[0-9;]*m/g, "").length)));
+  const line = (cells) => cells.map((x, i) => (cols[i].right ? " ".repeat(Math.max(0, widths[i] - String(x).replace(/\x1b\[[0-9;]*m/g, "").length)) + x : pad(x, widths[i]))).join("  ");
+  return [dim(line(cols.map((x) => x.label))), ...rows.map((r) => line(cols.map((x) => x.get(r))))].join("\n");
+}
+const out = (s = "") => process.stdout.write(s + "\n");
+
+// ---------------------------------------------------------------- api
+async function request(tool, input) {
+  if (!token) return { status: "error", tool, reason: "login_required", message: "Not signed in. Run: npx rosession login" };
+  let res;
+  try {
+    res = await fetch(`${base}/api/agent/${tool}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "User-Agent": `rosession-cli/${VERSION}` },
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (e) {
+    return { status: "error", tool, reason: "busy", message: `Couldn't reach ${base}: ${e.message}` };
+  }
+  return res.json().catch(() => ({ status: "error", tool, reason: "busy", message: `${base} answered ${res.status}` }));
+}
+
+// ---------------------------------------------------------------- pretty printers
+const P = {};
+P.games = (d) => {
+  if (!d.games.length) return out("No games yet. Add one at rosession.com/dashboard/new");
+  out(table(d.games, [
+    { label: "GAME", get: (g) => bold(g.name) },
+    { label: "ID", get: (g) => dim(g.id) },
+    { label: "ONLINE", right: true, get: (g) => (g.online ? green(num(g.online)) : "0") },
+    { label: "PLAYERS 24H", right: true, get: (g) => num(g.players24h) },
+    { label: "SESSIONS 24H", right: true, get: (g) => num(g.sessions24h) },
+    { label: "LAST DATA", get: (g) => ago(g.lastData) },
+  ]));
+};
+P.overview = (d) => {
+  const k = d.kpis;
+  const ch = d.change || {};
+  const rows = [
+    ["Players", num(k.users), ch.users],
+    ["New players", num(k.newUsers), ch.newUsers],
+    ["Sessions", num(k.sessions), ch.sessions],
+    ["Avg session", dur(k.avgSession), ch.avgSession],
+    ["Playtime", `${num(k.playtimeHours, 1)} h`, ch.playtimeHours],
+    ["Robux", `R$ ${num(k.revenue)}`, ch.revenue],
+    ["Paying players", pct(k.conversion), ch.conversion],
+    ["Peak online", num(k.peakCcu), ch.peakCcu],
+    ["Day 1 return", pct(k.d1), ch.d1],
+  ];
+  for (const [l, v, x] of rows) out(`  ${pad(dim(l), 16)} ${pad(bold(v), 12)}${delta(x)}`);
+  if (d.series?.length > 1) out(`\n  ${dim("Players")}  ${cyan(spark(d.series.map((s) => s.users)))}`);
+  if (d.leaveReasons?.length) {
+    out(`\n  ${bold("Why they left")}`);
+    const total = d.leaveReasons.reduce((a, r) => a + r.v, 0) || 1;
+    for (const r of d.leaveReasons.slice(0, 5)) out(`  ${pad(r.name, 30)} ${bar((r.v / total) * 100)} ${pct((r.v / total) * 100)}`);
+  }
+};
+P.live = (d) => {
+  out(`  ${green("●")} ${bold(num(d.online))} playing now on ${num(d.servers.length)} server${d.servers.length === 1 ? "" : "s"}   ${dim("last hour")} ${cyan(spark(d.lastHour.map((x) => x.v)))}`);
+  out(`  ${dim("Today:")} ${num(d.today?.users)} players · ${num(d.today?.sessions)} sessions · R$ ${num(d.today?.revenue)} · peak ${num(d.today?.peakCcu)}\n`);
+  if (d.players.length)
+    out(table(d.players.slice(0, 25), [
+      { label: "PLAYER", get: (p) => bold(p.display || p.name) + (p.is_new ? green(" new") : "") },
+      { label: "DOING", get: (p) => p.current_activity || dim("–") },
+      { label: "FOR", right: true, get: (p) => dur(p.seconds) },
+      { label: "DEVICE", get: (p) => p.platform || "–" },
+      { label: "FPS", right: true, get: (p) => (p.fps == null ? "–" : p.fps < 25 ? red(num(p.fps)) : num(p.fps)) },
+      { label: "IDLE", right: true, get: (p) => (p.idle_s > 60 ? dur(p.idle_s) : "") },
+    ]));
+};
+P.leaving = (d) => {
+  out(`  ${num(d.totalSessions)} sessions ended · ${pct(d.newPlayerShortSessions)} of first sessions were under a minute\n`);
+  for (const r of d.reasons) out(`  ${pad(r.name, 32)} ${bar(r.share)} ${pad(pct(r.share), 7)} ${dim(`avg ${dur(r.avg * 60)}`)}`);
+  if (d.lastActions?.length) out(`\n  ${dim("Last thing they did:")} ${d.lastActions.slice(0, 5).map((a) => `${a.name} (${num(a.v)})`).join(", ")}`);
+};
+P.sessions = (d) => {
+  out(dim(`  ${num(d.total)} sessions\n`));
+  out(table(d.sessions, [
+    { label: "WHEN", get: (s) => dim(ago(s.joined_at)) },
+    { label: "PLAYER", get: (s) => bold(s.name) + (s.is_new ? green(" new") : "") },
+    { label: "LENGTH", right: true, get: (s) => dur(s.duration_s) },
+    { label: "DEVICE", get: (s) => s.platform || "–" },
+    { label: "R$", right: true, get: (s) => (s.robux ? num(s.robux) : "") },
+    { label: "LEFT BECAUSE", get: (s) => s.leave_reason || green("still playing") },
+    { label: "ID", get: (s) => dim(s.id) },
+  ]));
+};
+P.updates = (d) => {
+  if (!d.current) return out("No place versions yet.");
+  const c = d.current;
+  const b = d.previous;
+  out(`  ${bold(`v${c.version}`)}${b ? dim(` vs v${b.version}`) : ""}  ${dim(`${num(c.sessions)} sessions`)}\n`);
+  const ch = d.change || {};
+  const rows = [
+    ["Players / day", num(c.playersPerDay, 1), ch.playersPerDay],
+    ["Avg session", dur(c.avgSession), ch.avgSession],
+    ["Sessions / player", num(c.sessionsPerPlayer, 2), ch.sessionsPerPlayer],
+    ["Bounce rate", pct(c.bounce), ch.bounce, true],
+    ["New player D1", pct(c.d1), ch.d1],
+    ["Paying players", pct(c.conversion), ch.conversion],
+    ["Robux / player", num(c.robuxPerPlayer, 2), ch.robuxPerPlayer],
+    ["Errors / 100", num(c.errorsPer100, 1), ch.errorsPer100, true],
+  ];
+  for (const [l, v, x, inv] of rows) out(`  ${pad(dim(l), 20)} ${pad(bold(v), 10)}${delta(x, inv)}`);
+  const fresh = (c.errors || []).filter((e) => e.isNew);
+  if (fresh.length) {
+    out(`\n  ${red("New errors")}`);
+    for (const e of fresh.slice(0, 5)) out(`  ${dim(`×${e.n}`)} ${e.message}`);
+  }
+};
+P.experiments = (d) => {
+  if (!d.tests.length) return out("No A/B tests in this period. Start one with RoSession.variant(player, name, variants).");
+  for (const t of d.tests) {
+    out(`  ${bold(t.name)} ${dim(`${num(t.players)} players · control ${t.control}`)}`);
+    out(table(t.variants, [
+      { label: "  VARIANT", get: (v) => `  ${v.name}` },
+      { label: "PLAYERS", right: true, get: (v) => num(v.players) },
+      { label: "PLAYTIME", right: true, get: (v) => `${num(v.playtime, 1)}m` + sig(v, "playtime") },
+      { label: "PAYING", right: true, get: (v) => pct(v.conversion) + sig(v, "conversion") },
+      { label: "R$/PLAYER", right: true, get: (v) => num(v.arpu, 2) + sig(v, "arpu") },
+      { label: "D1", right: true, get: (v) => pct(v.d1) + sig(v, "d1") },
+    ]));
+    out("");
+  }
+  out(dim("  * = significant (p < 0.05)"));
+};
+P.explain = (d) => {
+  out(`  ${bold(d.summary)}\n`);
+  // arrow = which way it moved; colour = good or bad for the game
+  const good = (x) => {
+    if (x.direction === "neutral") return cyan("•");
+    const arrow = x.direction === "up" ? "↑" : "↓";
+    const bad = ["leave_reason", "new_error", "errors", "crashes"].includes(x.kind) === (x.direction === "up");
+    return bad ? red(arrow) : green(arrow);
+  };
+  for (const x of d.drivers || []) out(`  ${good(x)} ${x.title}\n    ${dim(x.detail)}`);
+};
+P.timeline = (d) => {
+  if (d.summary) return P.explain(d);
+  if (!d.markers.length) return out("Nothing on the timeline in this period. Add notes on the Overview chart.");
+  for (const m of d.markers) out(`  ${dim(m.ts.slice(0, 16).replace("T", " "))}  ${pad(cyan(m.label), 14)} ${m.text}${m.by ? dim(` @${m.by}`) : ""}`);
+};
+const sig = (v, k) => (v.p?.[k] != null && v.p[k] < 0.05 ? green("*") : v.p ? " " : " ");
+
+function pretty(reply) {
+  if (reply.status !== "ok") {
+    out(red(`✗ ${reply.message || reply.reason}`));
+    if (reply.data?.games?.length) out(dim(`  Your games: ${reply.data.games.map((g) => `${g.name} (${g.id})`).join(", ")}`));
+    return;
+  }
+  const title = reply.game ? `${bold(reply.game.name)} ${dim("·")} ${reply.tool}` : bold(reply.tool);
+  const span = reply.period ? dim(` · ${reply.period.from.slice(0, 10)} → ${reply.period.to.slice(0, 10)}`) : "";
+  out(`\n${title}${span}\n`);
+  const fn = P[reply.tool];
+  if (fn) fn(reply.data);
+  else out(yaml(reply.data, 1));
+  out(`\n${dim("→")} ${cyan(reply.link)}`);
+  if (reply.next?.length) out(dim(`  next: ${reply.next.map((n) => n.command).join("  |  ")}`));
+  out("");
+}
+
+// readable dump for tools without their own printer
+function yaml(v, depth = 0) {
+  const ind = "  ".repeat(depth);
+  if (Array.isArray(v)) {
+    if (!v.length) return `${ind}${dim("(none)")}`;
+    if (v.every((x) => x && typeof x === "object" && !Array.isArray(x))) {
+      const keys = [...new Set(v.flatMap((x) => Object.keys(x).filter((k) => typeof x[k] !== "object" || x[k] === null)))].slice(0, 7);
+      return table(v.slice(0, 30), keys.map((k) => ({ label: k.toUpperCase(), get: (x) => (x[k] == null ? "–" : typeof x[k] === "number" ? num(x[k], 2) : String(x[k]).slice(0, 60)) })))
+        .split("\n")
+        .map((l) => ind + l)
+        .join("\n");
+    }
+    return ind + v.map((x) => (typeof x === "object" ? JSON.stringify(x) : x)).join(", ");
+  }
+  if (v && typeof v === "object")
+    return Object.entries(v)
+      .filter(([k]) => k !== "units")
+      .map(([k, x]) => (x && typeof x === "object" ? `${ind}${bold(k)}\n${yaml(x, depth + 1)}` : `${ind}${pad(dim(k), 22)} ${typeof x === "number" ? num(x, 2) : x}`))
+      .join("\n");
+  return ind + String(v);
+}
+
+// ---------------------------------------------------------------- commands
+const REQUIRED = { session: "id", player: "player" }; // the extra word after the game
+function inputFor(tool) {
+  const input = {};
+  for (const [k, v] of Object.entries(flags)) if (!["json", "url", "token", "help", "every"].includes(k)) input[k] = v === true ? true : /^\d+$/.test(v) ? Number(v) : v;
+  const [game, extra] = words.slice(1);
+  // public Roblox stats: the first word is that tool's main input, not one of your games
+  const FIRST = { roblox_search: "query", roblox_game: "universe_id", roblox_compare: "universe_ids", roblox_rankings: "list" };
+  if (FIRST[tool]) {
+    if (game !== undefined) input[FIRST[tool]] = game;
+  } else if (game !== undefined && tool !== "games") input.game = game;
+  if (extra !== undefined && REQUIRED[tool]) input[REQUIRED[tool]] = extra;
+  input.tz = -new Date().getTimezoneOffset();
+  return input;
+}
+
+async function login() {
+  if (typeof flags.token === "string") {
+    if (!/^rsa_[a-z0-9]{32}$/i.test(flags.token)) return fail("That doesn't look like a RoSession token (rsa_…).");
+    saveConfig({ ...config, url: base, token: flags.token });
+    token = flags.token;
+    return check();
+  }
+  // OAuth with PKCE, back to a one-time server on this computer
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const state = randomBytes(16).toString("base64url");
+  const server = createServer();
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  const redirect = `http://127.0.0.1:${server.address().port}/callback`;
+  const reg = await fetch(`${base}/api/oauth/register`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_name: "RoSession CLI", redirect_uris: [redirect] }) })
+    .then((r) => r.json())
+    .catch((e) => ({ error_description: e.message }));
+  if (!reg.client_id) return server.close(), fail(`Couldn't start sign-in: ${reg.error_description || "no client id"}`);
+  const url = `${base}/oauth/authorize?${new URLSearchParams({ response_type: "code", client_id: reg.client_id, redirect_uri: redirect, code_challenge: challenge, code_challenge_method: "S256", state, scope: "read" })}`;
+  const code = new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Timed out waiting for the browser (5 minutes).")), 300000);
+    server.on("request", (req, res) => {
+      const q = new URL(req.url, redirect).searchParams;
+      if (!req.url.startsWith("/callback")) return res.writeHead(404).end();
+      const ok = q.get("code") && q.get("state") === state;
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(`<!doctype html><meta charset="utf-8"><title>RoSession</title><body style="font:16px system-ui;background:#0b0c10;color:#eef0f5;display:grid;place-items:center;height:100vh;margin:0"><div style="text-align:center"><h2>${ok ? "Signed in ✓" : "Sign-in didn't finish"}</h2><p style="color:#9aa0ad">${ok ? "You can close this tab and go back to the terminal." : "Go back to the terminal and try again."}</p></div>`);
+      clearTimeout(timer);
+      ok ? resolve(q.get("code")) : reject(new Error(q.get("error_description") || q.get("error") || "Sign-in was cancelled."));
+    });
+  });
+  process.stderr.write(`Opening your browser to sign in with Roblox…\nIf it doesn't open, go to:\n\n  ${url}\n\n`);
+  openBrowser(url);
+  try {
+    const got = await code;
+    const t = await fetch(`${base}/api/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "authorization_code", code: got, code_verifier: verifier, client_id: reg.client_id, redirect_uri: redirect }),
+    }).then((r) => r.json());
+    if (!t.access_token) throw new Error(t.error_description || t.error || "No token");
+    saveConfig({ ...config, url: base, token: t.access_token });
+    token = t.access_token;
+  } catch (e) {
+    return fail(e.message);
+  } finally {
+    server.close();
+  }
+  return check();
+}
+
+async function check() {
+  const r = await request("games", {});
+  if (r.status !== "ok") return fail(r.message);
+  if (asJson) return out(JSON.stringify({ status: "ok", tool: "login", data: { games: r.data.games.length, config: configFile } }));
+  out(green("✓ Signed in.") + dim(` ${r.data.games.length} game${r.data.games.length === 1 ? "" : "s"}. Try: npx rosession overview`));
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd[0], cmd[1], { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch {}
+}
+
+async function watch() {
+  const every = Math.max(5, Number(flags.every) || 10) * 1000;
+  const input = inputFor("live");
+  for (;;) {
+    const r = await request("live", input);
+    if (asJson) out(JSON.stringify(r));
+    else {
+      process.stdout.write("\x1b[2J\x1b[H");
+      pretty(r);
+      out(dim(`  refreshing every ${every / 1000}s · ctrl+c to stop`));
+    }
+    if (r.status !== "ok" && ["login_required", "not_found", "missing_arguments"].includes(r.reason)) process.exit(1);
+    await new Promise((res) => setTimeout(res, every));
+  }
+}
+
+async function tools() {
+  const r = await fetch(`${base}/api/agent/tools`).then((x) => x.json()).catch(() => null);
+  if (!r) return fail(`Couldn't reach ${base}`);
+  if (asJson) return out(JSON.stringify(r));
+  out(`\n${bold("rosession <tool> [game] [--option value]")}\n`);
+  for (const t of r.tools) {
+    const opts = Object.keys(t.input.properties).filter((k) => k !== "game");
+    out(`  ${bold(pad(t.name, 13))} ${t.title}${t.light ? dim(" (free)") : ""}`);
+    if (opts.length) out(dim(`  ${" ".repeat(13)} --${opts.join(" --")}`));
+  }
+  out(`\n  ${bold(pad("watch", 13))} Live players, refreshed every 10 s (--every 15)`);
+  out(`  ${bold(pad("login", 13))} Sign in with Roblox (or --token rsa_…)`);
+  out(`  ${bold(pad("logout", 13))} Forget the saved token\n`);
+}
+
+function help() {
+  out(`${bold("rosession")} ${dim(VERSION)}: ask your Roblox game, from the terminal
+
+  ${cyan("npx rosession login")}                     sign in with Roblox
+  ${cyan("npx rosession games")}                     your games
+  ${cyan('npx rosession overview "My Game"')}        this week vs last  (--range 24h|7d|30d)
+  ${cyan('npx rosession leaving "My Game"')}         why players leave
+  ${cyan('npx rosession watch "My Game"')}           live players
+  ${cyan("npx rosession tools")}                     every command and option
+
+  --json for JSON (automatic when a program runs it) · ROSESSION_TOKEN to skip login
+  Docs: ${base}/docs#agents`);
+}
+
+function fail(message, code = 1) {
+  if (asJson) out(JSON.stringify({ status: "error", reason: "login_failed", message }));
+  else process.stderr.write(red(`✗ ${message}\n`));
+  process.exit(code);
+}
+
+// ---------------------------------------------------------------- main
+const cmd = words[0];
+if (!cmd || flags.help || cmd === "help") help();
+else if (cmd === "--version" || cmd === "version" || flags.version) out(VERSION);
+else if (cmd === "login") await login();
+else if (cmd === "logout") {
+  if (existsSync(configFile)) rmSync(configFile);
+  out(asJson ? JSON.stringify({ status: "ok", tool: "logout" }) : "Signed out.");
+} else if (cmd === "tools") await tools();
+else if (cmd === "watch") await watch();
+else {
+  const reply = await request(cmd, inputFor(cmd));
+  if (asJson) out(JSON.stringify(reply, null, flags.json === "pretty" ? 2 : 0));
+  else pretty(reply);
+  process.exitCode = reply.status === "ok" ? 0 : reply.reason === "login_required" ? 2 : 1;
+}

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "rosession",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Ask your Roblox game: RoSession analytics in your terminal and for AI agents (Claude Code, Codex, Cursor).",
+  "type": "module",
+  "bin": { "rosession": "bin/rosession.mjs" },
+  "files": ["bin", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["roblox", "analytics", "rosession", "cli", "mcp", "ai-agents"],
+  "homepage": "https://rosession.com/docs#agents",
+  "license": "MIT"
+}