@nanhara/hara 0.100.0 → 0.101.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.101.0 — startup update check
+
+- **`hara` tells you when it's out of date.** On launch (interactive TTY only), a one-line notice —
+  `⬆ Update available 0.100.0 → 0.101.0 · npm i -g @nanhara/hara` — driven by a daily background
+  probe with a 3s timeout that NEVER delays startup (the notice always comes from the previous
+  probe's cache, npm update-notifier style). npmjs first, npmmirror fallback for CN networks;
+  offline machines fail silent and back off to daily retries. Disable with
+  `hara config set updateCheck false` or `HARA_UPDATE_CHECK=0`.
+
 ## 0.100.0 — the agent keeps its own attention: system-reminders + anti-drift compaction
 
 Distilled from a source-level study of Claude Code v1.0.33's agent internals (the Ie1/WD5 reminder

package/dist/config.js

@@ -30,7 +30,7 @@ const PROVIDER_DEFAULTS = {
     },
     "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -158,6 +158,7 @@ export function loadConfig(opts = {}) {
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
+    const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
     const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
     const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
     const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
@@ -165,7 +166,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/index.js

@@ -25,6 +25,7 @@ import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile,
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
 import { shouldAutoCompact, COMPACT_SYSTEM } from "./agent/compact.js";
+import { checkForUpdate } from "./update-check.js";
 import { formatContextReport } from "./agent/context-report.js";
 import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
 import { checkpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
@@ -2187,6 +2188,13 @@ program.action(async (opts) => {
     // interactive REPL — ink TUI by default on a real terminal; HARA_TUI=0 forces the classic readline path
     const useTui = stdin.isTTY && stdout.isTTY && process.env.HARA_TUI !== "0";
     out(c.bold(`hara ${pkg.version}`) + c.dim(`  ·  ${cfg.provider}:${cfg.model}  ·  ${approval}${sandbox !== "off" ? `  ·  sandbox:${sandbox}` : ""}  ·  ${cwd}\n`));
+    // Startup update notice — cache-driven (a previous session's background probe), so it costs zero
+    // latency; today's probe (if due) fires in the background for the NEXT launch. TTY sessions only.
+    if (cfg.updateCheck && stdout.isTTY) {
+        const upd = checkForUpdate(pkg.version);
+        if (upd)
+            out(c.yellow(`⬆ ${upd}`) + "\n");
+    }
     const rl = createInterface({
         input: stdin,
         output: stdout,

package/dist/update-check.js

@@ -0,0 +1,83 @@
+// Startup update check (npm's update-notifier pattern): NEVER blocks or delays startup. The notice
+// shown at launch comes from a CACHE written by a previous session's background probe; if the cache
+// is stale (> a day) a fresh probe fires in the background with a hard timeout — its result shows on
+// the NEXT launch. Offline / blocked registries fail silently. Interactive TTY sessions only (the
+// caller gates); disable with `hara config set updateCheck false` or HARA_UPDATE_CHECK=0.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+const cacheFile = () => join(homedir(), ".hara", "update-check.json");
+/** Probe at most once a day — the check is a courtesy, not a heartbeat. */
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+/** npmjs first; the npmmirror fallback keeps the check working on CN networks where npmjs stalls. */
+const REGISTRIES = ["https://registry.npmjs.org/@nanhara/hara/latest", "https://registry.npmmirror.com/@nanhara/hara/latest"];
+/** Strict-ish semver compare on the numeric triple: is `latest` newer than `current`?
+ *  Anything unparsable (tags, garbage, empty) → false — never nag on bad data. */
+export function isNewer(latest, current) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const a = parse(latest);
+    const b = parse(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+export function readCache(file = cacheFile()) {
+    try {
+        const j = JSON.parse(readFileSync(file, "utf8"));
+        return typeof j?.checkedAt === "number" && typeof j?.latest === "string" ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(c, file = cacheFile()) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(c));
+    }
+    catch {
+        /* a failed cache write must never surface */
+    }
+}
+/** The startup notice, decided purely from cache state (testable without I/O). */
+export function updateNotice(current, cache) {
+    if (!cache || !isNewer(cache.latest, current))
+        return null;
+    return `Update available ${current} → ${cache.latest} · npm i -g @nanhara/hara`;
+}
+/** Background probe: first registry that answers wins; 3s hard timeout each; silent on total failure
+ *  (checkedAt still stamps so an offline machine backs off to daily retries, not every launch). */
+export async function refreshLatest(file = cacheFile(), fetchFn = fetch) {
+    for (const url of REGISTRIES) {
+        try {
+            const r = await fetchFn(url, { signal: AbortSignal.timeout(3000) });
+            if (!r.ok)
+                continue;
+            const j = (await r.json());
+            if (j?.version) {
+                writeCache({ checkedAt: Date.now(), latest: j.version }, file);
+                return;
+            }
+        }
+        catch {
+            /* offline / blocked / slow → try the next registry, then give up quietly */
+        }
+    }
+    const prev = readCache(file);
+    writeCache({ checkedAt: Date.now(), latest: prev?.latest ?? "" }, file);
+}
+/** Startup entry: return the notice to print (or null), and — when the cache is stale — fire the
+ *  daily background probe (fire-and-forget; the caller never awaits it). */
+export function checkForUpdate(current, file = cacheFile(), now = Date.now()) {
+    const cache = readCache(file);
+    if (!cache || now - cache.checkedAt > CHECK_EVERY_MS)
+        void refreshLatest(file).catch(() => { });
+    return updateNotice(current, cache);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"