@hmharness/cli 0.2.0 → 0.3.0

package/dist/main.js

@@ -8,7 +8,7 @@
  *   hmh resume [id-prefix]   continue a past session by id prefix (or latest)
  *   hmh web [--port=7788]    local web frontend (SSE streaming + approvals)
  *   hmh tui                  lite terminal UI (status header + slash commands)
- *   hmh ops [scan|brief|status]  ops keeper: ecosystem radar
+ *   hmh ops [scan|brief|stats|status]  ops keeper: radar / npm download stats
  *   hmh devices|check        direct tool run, no model
  *   hmh tools                list all registered tools (native + MCP)
  *   hmh mcp                  show configured MCP servers and their tools
@@ -98,6 +98,14 @@ async function repl(yes, initialHistory) {
     let t = strings((cfg.locale ?? 'zh'));
     const header = () => stdout.write(CYAN('hmh') + DIM(` · ${cfg.provider.model} · ${home}\n`));
     stdout.write(CYAN('hmh') + DIM(` · ${cfg.provider.model} · ${home}\n`) + DIM(`${t.replHint} · /help ${String(t.cmdHelp)}\n\n`));
+    // npm is pull-based; the update reminder is a cached (1/day) registry
+    // check printed when resolved - never blocks, never nags offline
+    const { notifyUpdate } = await import("./update-check.js");
+    const { createRequire } = await import('node:module');
+    const CURRENT_VERSION = createRequire(import.meta.url)('../package.json').version;
+    void notifyUpdate(home, CURRENT_VERSION, (latest) => {
+        stdout.write(DIM(`↑ ${t.updateHint(latest)}\n\n`));
+    });
     const { reg, clients } = await buildRegistry();
     const rl = readline.createInterface({ input: stdin, output: stdout });
     // stdin EOF (piped input, closed terminal) must exit the loop - a bare
@@ -325,7 +333,7 @@ usage:
   hmh web [--port=7788]       web UI in the foreground (debugging)
   hmh tui [--no-web]      fullscreen terminal UI (slash palette, mouse wheel);
                            also starts the web UI in the background (--no-web skips)
-  hmh ops [scan|brief|status]  ops keeper: ecosystem radar
+  hmh ops [scan|brief|stats|status]  ops keeper: radar / npm download stats
   hmh mcp-serve        run as an MCP stdio SERVER: expose harmony_* tools to
                         Claude Code / Codex / any MCP host
                         (host config: npx -y @hmharness/cli mcp-serve)
@@ -577,6 +585,16 @@ flags:
             const r = await harmonyOpsRadarBrief.execute({}, ctx);
             stdout.write(r.output + '\n');
         }
+        else if (sub === 'stats') {
+            // npm download counts for the seven packages (public API, no auth).
+            const { fetchNpmStats, renderStats } = await import("./npm-stats.js");
+            try {
+                stdout.write(renderStats(await fetchNpmStats()) + '\n');
+            }
+            catch {
+                stdout.write('npm downloads API unreachable right now - try again later\n');
+            }
+        }
         else {
             const r = await harmonyOpsStatus.execute({}, ctx);
             stdout.write(r.output + '\n');

package/dist/npm-stats.d.ts

@@ -0,0 +1,8 @@
+export interface PkgStat {
+    name: string;
+    day: number | null;
+    week: number | null;
+    month: number | null;
+}
+export declare function fetchNpmStats(fetchImpl?: typeof fetch): Promise<PkgStat[]>;
+export declare function renderStats(rows: PkgStat[]): string;

package/dist/npm-stats.js

@@ -0,0 +1,41 @@
+/**
+ * @hmharness/cli - npm-stats
+ * `hmh ops stats`: download counts for the seven @hmharness packages from
+ * npm's public downloads API. Counts are DOWNLOADS, not users - mirror sync
+ * and scanners are included; the line under the table says so (honesty over
+ * vanity metrics).
+ */
+const PKGS = ['kernel', 'evolution', 'domain-harmony', 'domain-ops', 'agent', 'web', 'cli'];
+async function one(fetchImpl, period, name) {
+    try {
+        const res = await fetchImpl(`https://api.npmjs.org/downloads/point/${period}/${encodeURIComponent(name)}`, {
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return typeof j.downloads === 'number' ? j.downloads : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function fetchNpmStats(fetchImpl = fetch) {
+    const rows = await Promise.all(PKGS.map(async (p) => {
+        const name = '@hmharness/' + p;
+        const [day, week, month] = await Promise.all([
+            one(fetchImpl, 'last-day', name),
+            one(fetchImpl, 'last-week', name),
+            one(fetchImpl, 'last-month', name),
+        ]);
+        return { name, day, week, month };
+    }));
+    return rows;
+}
+export function renderStats(rows) {
+    const n = (v) => (v === null ? '-' : String(v));
+    const w = (s, len) => s.padEnd(len);
+    const head = w('package', 28) + w('day', 7) + w('week', 8) + 'month';
+    const body = rows.map((r) => w(r.name, 28) + w(n(r.day), 7) + w(n(r.week), 8) + n(r.month)).join('\n');
+    return head + '\n' + body + '\n(downloads, not users: mirror sync + scanners included; CN installs via npmmirror are NOT counted)';
+}

package/dist/tui.js

@@ -831,6 +831,14 @@ export async function tui(yes, noWeb = false) {
     rt.addText(t.tuiWelcome(chatModel), 'dim');
     if (webUp)
         rt.addText(t.tuiWebLinked(DEFAULT_WEB_PORT), 'dim');
+    // update reminder: cached (1/day) registry check, resolved async into the
+    // transcript via addText (frame-safe); offline stays silent
+    {
+        const { notifyUpdate } = await import("./update-check.js");
+        const { createRequire } = await import('node:module');
+        const current = createRequire(import.meta.url)('../package.json').version;
+        void notifyUpdate(home, current, (latest) => rt.addText(`↑ ${t.updateHint(latest)}`, 'dim'));
+    }
     let history = [];
     rt.onSubmit(() => {
         const line = rt.consumeInput().trim();

package/dist/update-check.d.ts

@@ -0,0 +1,19 @@
+/** Numeric per-component semver compare (no dependency, dot-split).
+ *  Prerelease suffixes degrade to their leading number ('1-beta' -> 1) -
+ *  good enough for an update hint, never claims to be full semver. */
+export declare function cmpSemver(a: string, b: string): number;
+export interface UpdateInfo {
+    current: string;
+    latest: string;
+}
+/** Returns info when a NEWER version exists on the registry, else null.
+ *  Cache-first: a fresh (<24h) cached latest answer means zero network. */
+export declare function checkForUpdate(opts: {
+    home: string;
+    current: string;
+    now?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<UpdateInfo | null>;
+/** Fire-and-forget wrapper for interactive frontends: resolve-and-say, or
+ *  say nothing at all. Never rejects. */
+export declare function notifyUpdate(home: string, current: string, say: (line: string) => void): Promise<void>;

package/dist/update-check.js

@@ -0,0 +1,67 @@
+/**
+ * @hmharness/cli - update-check
+ * npm is pull-based: there is no server-side push. The honest "update
+ * reminder" is a client-side version check against the registry's latest
+ * dist-tag, printed once per interactive session - never blocking startup,
+ * never nagging offline, results cached for a day.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const REGISTRY = 'https://registry.npmjs.org/-/package/@hmharness/cli/dist-tags';
+const CACHE_TTL_MS = 24 * 3600_000;
+/** Numeric per-component semver compare (no dependency, dot-split).
+ *  Prerelease suffixes degrade to their leading number ('1-beta' -> 1) -
+ *  good enough for an update hint, never claims to be full semver. */
+export function cmpSemver(a, b) {
+    const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) < (pb[i] ?? 0) ? -1 : 1;
+    }
+    return 0;
+}
+/** Returns info when a NEWER version exists on the registry, else null.
+ *  Cache-first: a fresh (<24h) cached latest answer means zero network. */
+export async function checkForUpdate(opts) {
+    const now = opts.now ?? Date.now();
+    const cacheFile = join(opts.home, 'update-check.json');
+    let latest = null;
+    try {
+        const c = JSON.parse(await readFile(cacheFile, 'utf8'));
+        if (typeof c.latest === 'string' && now - c.time < CACHE_TTL_MS)
+            latest = c.latest;
+    }
+    catch { /* no cache yet */ }
+    if (latest === null) {
+        const doFetch = opts.fetchImpl ?? fetch;
+        try {
+            const res = await doFetch(REGISTRY, { signal: AbortSignal.timeout(3000) });
+            if (res.ok) {
+                const tags = await res.json();
+                if (typeof tags.latest === 'string') {
+                    latest = tags.latest;
+                    try {
+                        await mkdir(opts.home, { recursive: true });
+                        await writeFile(cacheFile, JSON.stringify({ time: now, latest }), 'utf8');
+                    }
+                    catch { /* cache write is best-effort */ }
+                }
+            }
+        }
+        catch { /* offline / slow registry: silent, never nag */ }
+    }
+    if (latest === null || cmpSemver(opts.current, latest) >= 0)
+        return null;
+    return { current: opts.current, latest };
+}
+/** Fire-and-forget wrapper for interactive frontends: resolve-and-say, or
+ *  say nothing at all. Never rejects. */
+export async function notifyUpdate(home, current, say) {
+    try {
+        const info = await checkForUpdate({ home, current });
+        if (info)
+            say(info.latest);
+    }
+    catch { /* never surface update-check failures */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "hmharness command line: one-shot tasks, an interactive REPL, a fullscreen TUI, the web frontend, and direct tool invocation.",
   "type": "module",
   "main": "dist/main.js",
@@ -43,11 +43,11 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.2.0",
-    "@hmharness/evolution": "0.2.0",
-    "@hmharness/domain-harmony": "0.2.0",
-    "@hmharness/domain-ops": "0.2.0",
-    "@hmharness/agent": "0.2.0",
-    "@hmharness/web": "0.2.0"
+    "@hmharness/kernel": "0.3.0",
+    "@hmharness/evolution": "0.3.0",
+    "@hmharness/domain-harmony": "0.3.0",
+    "@hmharness/domain-ops": "0.3.0",
+    "@hmharness/agent": "0.3.0",
+    "@hmharness/web": "0.3.0"
   }
 }