@kitsunemori96/open-session-metrics 0.3.0 → 0.3.1

package/README.md

@@ -24,13 +24,9 @@ osm                     # 起服务并打开浏览器
 osm status              # 谁在跑、数据在哪
 osm logs                # 跟踪服务日志
 osm stop                # 停掉后台服务
+osm upgrade             # 装最新版（--check 只看不装）
 ```
 
-> 0.3.0 起项目从 `opencode-session-metrics` 改名为 **Open Session Metrics**（包名
-> `@kitsunemori96/open-session-metrics`，CLI 仍是 `osm`）。旧包会标记 deprecated；
-> 已全局安装旧包的用户重装一次即可。旧的数据目录
-> `~/.local/share/opencode-session-metrics` 会被继续沿用，不迁移、不丢历史。
-
 要求 **Node 24+**（使用内置 `node:sqlite`，无原生依赖），且本机至少有一种数据源：
 `~/.local/share/opencode/opencode.db`（OpenCode）或 `~/.qoder/projects`（Qoder CLI）。
 默认源自动探测，也可以 `OSM_SOURCE=qoder osm` 指定，或启动后在页眉切换
@@ -38,6 +34,39 @@ osm stop                # 停掉后台服务
 `~/.local/share/open-session-metrics`（`OSM_DATA_DIR` 或 `osm --data` 可改），
 升级包不会动到它。`osm run` 前台运行，`--port` / `--host` 改绑定。
 
+### 更新
+
+`osm` 每 24 小时查一次 npm registry，结果缓存在数据目录的 `update-check.json`。
+有新版本时，`osm start` / `osm run` / `osm status` 末尾追加一行（走 stderr，
+`status` 的 stdout 仍可直接解析）：
+
+```
+osm: 0.3.1 available (running 0.3.0) — osm upgrade
+```
+
+`osm upgrade` 用当前的安装方式（npm / pnpm / yarn / bun）装 `@latest`，服务在跑就
+顺手重启到新版本；`osm upgrade --check` 只报告、不安装。检查失败只留缓存、一天内
+不再重试，`CI` 环境整个跳过，`OSM_OFFLINE=1` 不联网（仍可读已有缓存），
+`OSM_NO_UPDATE_CHECK=1` 彻底关掉。通过旧包桥接安装的副本不会原地升级——那会把旧
+名字一直留在最外层——而是打印「卸旧装新」两条命令（见[从旧包迁移](#从旧包迁移)）。
+源码 checkout 里 `osm upgrade` 会拒绝执行并提示 `git pull`，避免包管理器覆盖工作区。
+
+### 从旧包迁移
+
+0.3.0 起项目从 `opencode-session-metrics` 改名为 **Open Session Metrics**。旧包收到了
+一个 0.3.0 桥接版：它依赖新包并转调 `osm`，所以 `npm update -g` 之后旧名字仍然可用，
+跑的是新代码。
+
+```bash
+npm update -g @kitsunemori96/opencode-session-metrics   # 拉桥接版：命令、数据都不变
+npm uninstall -g @kitsunemori96/opencode-session-metrics
+npm i -g @kitsunemori96/open-session-metrics           # 想彻底换成新名字时
+```
+
+数据目录沿用旧的 `~/.local/share/opencode-session-metrics`（新目录不存在时），
+`OSM_*` 环境变量与 `osm` 命令不变，指标库不需要重建。两个包都提供 `osm`，
+所以切换时要先卸旧再装新，否则卸载旧包可能带走命令链接。
+
 从源码运行见[快速开始](#快速开始)。
 
 ## 界面
@@ -355,7 +384,8 @@ pid 与日志落在数据目录的 `osm.{pid,log}`。
 pnpm dev                    # server + web
 pnpm serve                  # 构建 + 重启 8787（见「快速开始」）
 pnpm typecheck              # 两个包 tsc --noEmit
-pnpm test                   # ETL / Qoder / 数据源 / 不变量测试（离线 fixture，无需服务与网络）
+pnpm test                   # ETL / Qoder / 数据源 / 不变量测试 + CLI 更新检查（离线 fixture，无需服务与网络）
+pnpm test:cli               # 只跑 CLI 更新检查的单元测试（node:test）
 pnpm -F @osm/server test:smoke   # HTTP 冒烟测试（需服务在线）
 pnpm materialize            # 增量物化
 pnpm materialize --full     # 全量重建（写入临时文件后原子替换）
@@ -374,10 +404,12 @@ pnpm plans                  # 按两库实测单价算套餐性价比（见 docs
 | `OSM_SOURCE` | 自动 | 默认数据源：`opencode` 或 `qoder`（页眉可切换，不设则自动探测） |
 | `OSM_SOURCE_DB` | `~/.local/share/opencode/opencode.db` | OpenCode 源库路径（只读） |
 | `OSM_QODER_HOME` | `~/.qoder` | Qoder 数据根目录（读其下 `projects/` 与 `logs/`） |
-| `OSM_DATA_DIR` | `<项目根>/.data` | 两库（`metrics.db` / `metrics-qoder.db`）与价目缓存目录（已 gitignore） |
+| `OSM_DATA_DIR` | `<项目根>/.data` | 两库（`metrics.db` / `metrics-qoder.db`）、价目与更新检查缓存（已 gitignore） |
 | `OSM_HOST` | `127.0.0.1` | API 监听地址 |
 | `OSM_PORT` | `8787` | API 端口 |
-| `OSM_OFFLINE` | — | 设为 `1` 时不访问 models.dev，价目走缓存或零值兜底 |
+| `OSM_OFFLINE` | — | 设为 `1` 时不访问 models.dev 与 npm 更新检查（版本检查仍可读缓存） |
+| `OSM_NO_UPDATE_CHECK` | — | 设为 `1` 关闭每日版本检查，不写缓存也不发请求 |
+| `OSM_UPDATE_REGISTRY` | `https://registry.npmjs.org` | 版本检查用的 registry（未设时沿用 `npm_config_registry`） |
 
 ## 实测性能
 
@@ -407,7 +439,8 @@ Qoder 的语料是另一套量级：67MB 逐行转录 · 24 个会话（含 8
 ## 目录结构
 
 ```
-bin/osm.js                # npm 入口：起服务、开浏览器、stop/status/logs
+bin/osm.js                # npm 入口：起服务、开浏览器、stop/status/logs/upgrade
+bin/update-check.js       # 每日一次的 registry 版本检查（纯函数，离线可测）
 server/src/
 ├── index.ts              # 启动、静态托管、水位驱动的刷新循环
 ├── api.ts                # REST 端点（每库一份，x-osm-source 选库）

package/bin/osm.js

@@ -11,7 +11,7 @@
 // One process, one port: Express serves both the API and the built web bundle.
 // State goes to the XDG data dir (`~/.local/share/open-session-metrics`), never
 // into the package directory, so `npm i -g` upgrades cannot delete it.
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import {
   createReadStream,
   existsSync,
@@ -26,6 +26,7 @@ import {
 import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkForUpdate, isNewer } from "./update-check.js";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const PKG = JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8"));
@@ -48,6 +49,7 @@ Usage
   osm status              process, URL, data dir, source db, bundle age
   osm logs [-n N]         follow the server log (default: last 40 lines)
   osm open                open the browser only
+  osm upgrade [--check]   install the latest release globally (--check only reports)
 
 Options
   --port <n>     listen port (default: $OSM_PORT or 8787)
@@ -58,10 +60,14 @@ Options
   -f, --foreground  same as \`osm run\`
   -v, --version  print the version
   -h, --help     print this help
+
+Updates
+  osm checks the npm registry once a day and prints one line when a newer
+  release exists. OSM_NO_UPDATE_CHECK=1 disables the check.
 `;
 
 const argv = process.argv.slice(2);
-const flags = { open: true, foreground: false };
+const flags = { open: true, foreground: false, check: false };
 const positional = [];
 let logLines = 40;
 
@@ -101,6 +107,9 @@ for (let i = 0; i < argv.length; i += 1) {
     case "--foreground":
       flags.foreground = true;
       break;
+    case "--check":
+      flags.check = true;
+      break;
     case "-n":
       logLines = Number(argv[(i += 1)]);
       break;
@@ -112,6 +121,7 @@ for (let i = 0; i < argv.length; i += 1) {
 
 const command = positional[0] ?? "start";
 if (positional.length > 1) fail(`unexpected argument: ${positional[1]}`);
+if (flags.check && command !== "upgrade") fail("--check is only valid with `osm upgrade`");
 
 const HOST = flags.host ?? process.env.OSM_HOST ?? "127.0.0.1";
 const PORT = flags.port ?? Number(process.env.OSM_PORT ?? 8787);
@@ -129,6 +139,7 @@ const USER_DATA_DIR = (() => {
   return existsSync(legacy) && !existsSync(current) ? legacy : current;
 })();
 const DEFAULT_DATA_DIR = ROOT.includes(INSTALLED) ? USER_DATA_DIR : path.join(ROOT, ".data");
+const IS_INSTALLED = ROOT.includes(INSTALLED);
 const DATA_DIR = path.resolve(flags.data ?? process.env.OSM_DATA_DIR ?? DEFAULT_DATA_DIR);
 const SOURCE_DB =
   flags.source ??
@@ -301,6 +312,16 @@ function checkInstall() {
 }
 
 async function start(foreground) {
+  const notice = updateNotice().catch(() => undefined);
+  try {
+    await startServer(foreground);
+  } finally {
+    // The check decorates the command; it must never change its outcome.
+    await notice;
+  }
+}
+
+async function startServer(foreground) {
   checkInstall();
 
   if (await isUp()) {
@@ -411,6 +432,7 @@ async function stop() {
 }
 
 async function status() {
+  const notice = updateNotice().catch(() => undefined);
   const pid = readPid();
   const up = await isUp();
   // One lookup either way: a pid file is authoritative, the listener is the fallback.
@@ -435,6 +457,119 @@ async function status() {
   } else {
     note("  bundle  missing");
   }
+  await notice;
+}
+
+/** Set once this process has installed a newer release: PKG.version is stale. */
+let upgraded = false;
+
+/**
+ * One line on stderr at most once a day. stdout stays parseable for `status`,
+ * and a slow or missing registry is silent rather than a delayed command.
+ */
+async function updateNotice() {
+  if (!IS_INSTALLED || upgraded) return;
+  const info = await checkForUpdate({ name: PKG.name, current: PKG.version, dataDir: DATA_DIR });
+  if (!info?.newer) return;
+  process.stderr.write(`osm: ${info.latest} available (running ${PKG.version}) — osm upgrade\n`);
+}
+
+const BRIDGE_PACKAGE = "@kitsunemori96/opencode-session-metrics";
+const MANAGERS = {
+  npm: { install: (spec) => ["install", "-g", spec], uninstall: (name) => ["uninstall", "-g", name] },
+  pnpm: { install: (spec) => ["add", "-g", spec], uninstall: (name) => ["remove", "-g", name] },
+  yarn: { install: (spec) => ["global", "add", spec], uninstall: (name) => ["global", "remove", name] },
+  bun: { install: (spec) => ["add", "-g", spec], uninstall: (name) => ["remove", "-g", name] },
+};
+
+/** Which tool owns the global prefix, inferred from where this file lives. */
+function globalManager() {
+  const root = ROOT.toLowerCase();
+  const sep = path.sep;
+  if (process.env.PNPM_HOME && root.startsWith(path.join(process.env.PNPM_HOME, "global").toLowerCase())) return "pnpm";
+  if (root.includes(`${sep}pnpm${sep}global${sep}`)) return "pnpm";
+  if (root.includes(`${sep}.bun${sep}install${sep}global${sep}`)) return "bun";
+  if (root.includes(`${sep}yarn${sep}global${sep}`) || root.includes(`${sep}.config${sep}yarn${sep}`)) return "yarn";
+  return "npm";
+}
+
+/**
+ * The bridge package installs the renamed one as a nested dependency:
+ * <prefix>/node_modules/@kitsunemori96/opencode-session-metrics/node_modules/@kitsunemori96/open-session-metrics
+ * Upgrading that in place would keep the old top-level name forever, so the
+ * migration is left to the user, printed as the two commands that end it.
+ */
+const installedThroughBridge = () =>
+  ROOT.toLowerCase().includes(`${path.sep}opencode-session-metrics${path.sep}node_modules${path.sep}`);
+
+const commandLine = (manager, args) => [manager, ...args].join(" ");
+
+/** Windows installs npm/pnpm/yarn as `.cmd` shims; `onPath("npm")` would miss them. */
+function managerBin(manager) {
+  if (process.platform !== "win32") return onPath(manager) ? manager : null;
+  return [`${manager}.cmd`, `${manager}.exe`, manager].find(onPath) ?? null;
+}
+
+async function upgrade() {
+  if (!flags.check && !IS_INSTALLED) {
+    fail("this is a source checkout — update with: git pull && pnpm install && pnpm serve");
+  }
+
+  const spec = `${PKG.name}@latest`;
+  const manager = globalManager();
+  const { install, uninstall } = MANAGERS[manager];
+
+  // Answer the migration question before the registry: it needs no network,
+  // and `@latest` is the spec either way.
+  if (!flags.check && installedThroughBridge()) {
+    note("this copy was installed by the deprecated @kitsunemori96/opencode-session-metrics bridge");
+    note(`  ${commandLine(manager, uninstall(BRIDGE_PACKAGE))}`);
+    note(`  ${commandLine(manager, install(spec))}`);
+    note("the osm command, OSM_* variables and the data dir all survive the switch");
+    process.exit(1);
+  }
+
+  const info = await checkForUpdate({
+    name: PKG.name,
+    current: PKG.version,
+    dataDir: DATA_DIR,
+    force: true,
+    // The user is waiting on this one, but a slow registry is still bounded.
+    timeout: 4000,
+  });
+
+  if (flags.check) {
+    if (info?.error) fail(`could not check the registry (${info.error})`);
+    if (info.newer) note(`${info.latest} available (running ${PKG.version}) — osm upgrade`);
+    else if (isNewer(PKG.version, info.latest)) note(`running ${PKG.version}; the registry has ${info.latest}`);
+    else note(`${PKG.version} is the latest`);
+    return;
+  }
+
+  if (info?.error) note(`could not check the registry (${info.error}) — installing ${spec} anyway`);
+  else if (!info.newer) {
+    note(`${PKG.version} is already the latest`);
+    return;
+  } else note(`installing ${info.latest} (running ${PKG.version})…`);
+
+  const args = install(spec);
+  const bin = managerBin(manager);
+  if (!bin) fail(`${manager} is not on PATH — run: ${commandLine(manager, args)}`);
+
+  const wasUp = await isUp();
+  const child = spawnSync(bin, args, { stdio: "inherit" });
+  if (child.error) fail(`${manager} failed: ${child.error.message}`);
+  if (child.status !== 0) fail(`${manager} exited with status ${child.status}`);
+
+  // This process still has the old version in memory; restart would otherwise
+  // announce the release it just installed as an available update.
+  upgraded = true;
+  if (wasUp) {
+    note("installed — restarting the server on the new version");
+    await restart();
+  } else {
+    note("installed — start it with: osm");
+  }
 }
 
 function follow() {
@@ -473,6 +608,9 @@ switch (command) {
   case "status":
     await status();
     break;
+  case "upgrade":
+    await upgrade();
+    break;
   case "logs":
   case "log":
     follow();

package/bin/update-check.js

@@ -0,0 +1,132 @@
+// Once-a-day registry lookups, kept out of bin/osm.js so the logic can be
+// tested without spawning a server and without touching the network.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const FETCH_TIMEOUT_MS = 1200;
+const CACHE_FILE = "update-check.json";
+
+/** `0.3.1`, `v0.3.1`, `0.3.1-rc.1` → parts; anything else → null. */
+export function parseVersion(input) {
+  if (typeof input !== "string") return null;
+  const match = input.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    pre: match[4] ?? null,
+  };
+}
+
+export function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return 0;
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
+  }
+  // A release outranks any prerelease of the same core: 0.3.1 > 0.3.1-rc.1.
+  if (left.pre === right.pre) return 0;
+  if (left.pre === null) return 1;
+  if (right.pre === null) return -1;
+  return left.pre < right.pre ? -1 : 1;
+}
+
+export const isNewer = (candidate, current) => compareVersions(candidate, current) > 0;
+
+/** Scoped names must be percent-encoded on the `/latest` route. */
+export function registryUrl(name, registry = DEFAULT_REGISTRY) {
+  const base = (registry || DEFAULT_REGISTRY).replace(/\/+$/, "");
+  return `${base}/${name.replace("/", "%2F")}/latest`;
+}
+
+export const cachePath = (dataDir) => path.join(dataDir, CACHE_FILE);
+
+export function readCache(file, name, now = Date.now()) {
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    if (!raw || raw.package !== name || !Number.isFinite(raw.checkedAt)) return null;
+    if (raw.latest !== null && typeof raw.latest !== "string") return null;
+    return { latest: raw.latest, checkedAt: raw.checkedAt, fresh: now - raw.checkedAt < CHECK_INTERVAL_MS };
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(file, name, latest, now = Date.now()) {
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ package: name, checkedAt: now, latest }, null, 2)}\n`);
+  } catch {
+    // A read-only or full data dir must not fail a command that was only checking.
+  }
+}
+
+async function fetchLatest({ name, registry, fetchImpl, timeout }) {
+  const res = await fetchImpl(registryUrl(name, registry), {
+    signal: AbortSignal.timeout(timeout),
+    headers: { accept: "application/json" },
+  });
+  if (!res.ok) throw new Error(`registry → HTTP ${res.status}`);
+  const body = await res.json();
+  if (!body || typeof body.version !== "string") throw new Error("registry response has no version");
+  return body.version;
+}
+
+/**
+ * The latest published version, from cache when it is under 24h old.
+ *
+ * `force` is for `osm upgrade`, where the user asked right now: it skips the
+ * cache, the daily opt-out and the offline guard. Ambient calls stay silent on
+ * failure and fall back to the last stored answer.
+ *
+ * A failure also writes the cache (`latest: null`, or the previous answer), so
+ * an unreachable registry costs one timeout per day rather than one per command.
+ */
+export async function checkForUpdate({
+  name,
+  current,
+  dataDir,
+  env = process.env,
+  fetchImpl = fetch,
+  now = Date.now(),
+  force = false,
+  timeout = FETCH_TIMEOUT_MS,
+}) {
+  if (!force && (env.OSM_NO_UPDATE_CHECK || env.CI)) return null;
+
+  const file = cachePath(dataDir);
+  const cached = readCache(file, name, now);
+  if (!force && cached?.fresh) {
+    return cached.latest === null ? null : result(cached.latest, current, "cache");
+  }
+
+  if (!force && env.OSM_OFFLINE) {
+    // Offline still honours a stored answer, but never opens a socket.
+    return cached && cached.latest !== null ? result(cached.latest, current, "cache") : null;
+  }
+
+  try {
+    const latest = await fetchLatest({
+      name,
+      registry: env.OSM_UPDATE_REGISTRY || env.npm_config_registry,
+      fetchImpl,
+      timeout,
+    });
+    writeCache(file, name, latest, now);
+    return result(latest, current, "registry");
+  } catch (error) {
+    writeCache(file, name, cached?.latest ?? null, now);
+    // Keep the error on the cached answer: an ambient notice ignores it, but
+    // `osm upgrade --check` must not report stale data as a fresh answer.
+    if (cached && cached.latest !== null) return { ...result(cached.latest, current, "cache"), error: error.message };
+    return { error: error.message, current };
+  }
+}
+
+function result(latest, current, from) {
+  return { latest, current, from, newer: isNewer(latest, current) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsunemori96/open-session-metrics",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A local-first web cockpit for coding session metrics across OpenCode and Qoder: tokens, cost, tools, and transcripts.",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,8 @@
     "plans": "pnpm -F @osm/server plans",
     "start": "pnpm -F @osm/server start",
     "typecheck": "pnpm -r typecheck",
-    "test": "pnpm -r test"
+    "test": "pnpm -r test && node --test test/update-check.test.mjs",
+    "test:cli": "node --test test/update-check.test.mjs"
   },
   "dependencies": {
     "cors": "^2.8.5",