sealkeep 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 Notable changes, by published version. Sealkeep is pre-1.0: minor versions
 may change behavior, and say so here when they do.
 
+## 0.11.2 — 2026-09-18 — a release tells you when a newer one exists
+
+- Sealkeep says, once a day at most, when a newer release is on npm and what
+  to run. A person finds out from the tool they already have open, or not at
+  all: 0.11.0 sat on the registry for two days unable to open a 0.11.1 vault's
+  predecessor, and nobody running it could learn the fix existed. The note
+  prints after the command's own output, never before it and never instead of
+  it, including when the command failed. The answer is cached per machine, so
+  a scripted loop makes no traffic; a failed check counts as the day's check,
+  so an offline machine stops asking. It is silent on every failure, skipped
+  for `--json`, hooks, the daemon, the MCP server and any non-terminal output,
+  and turned off for good with `SEALKEEP_NO_UPDATE_CHECK=1` (or the
+  conventional `NO_UPDATE_NOTIFIER=1`). Nothing is sent: it reads the same
+  public package metadata `npm view` reads.
+
 ## 0.11.1 — 2026-09-18 — an upgrade keeps what you already sealed
 
 Found by installing the published 0.9.0 from npm, building a vault with it,

package/dist/src/cli.js

@@ -274,6 +274,27 @@ function usage() {
         `${dim("Docs:")} README.md ${dim("·")} ${dim("Security:")} THREAT_MODEL.md\n`
     ].join("\n");
 }
+/**
+ * This install's own package manifest. The file sits one level up from
+ * dist/src but two from src/, so a fixed relative path is right in exactly one
+ * of development and the published package: walk up until our own is found.
+ */
+async function ownManifest() {
+    const { readFile } = await import("node:fs/promises");
+    const { dirname, join } = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let up = 0; up < 5; up += 1) {
+        try {
+            const found = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+            if (found?.name === "sealkeep" || found?.name === "vaultline")
+                return found;
+        }
+        catch { /* keep walking */ }
+        dir = dirname(dir);
+    }
+    return null;
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     const json = args.includes("--json");
@@ -284,20 +305,7 @@ async function main() {
         // The manifest sits one level up from dist/src but two from src/, so a fixed
         // relative path is right in exactly one of dev and the published package.
         // Walk up until we find our own manifest instead.
-        const { readFile } = await import("node:fs/promises");
-        const { dirname, join } = await import("node:path");
-        const { fileURLToPath } = await import("node:url");
-        let dir = dirname(fileURLToPath(import.meta.url));
-        let manifest = null;
-        for (let up = 0; up < 5 && !manifest; up += 1) {
-            try {
-                const found = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
-                if (found?.name === "sealkeep" || found?.name === "vaultline")
-                    manifest = found;
-            }
-            catch { /* keep walking */ }
-            dir = dirname(dir);
-        }
+        const manifest = await ownManifest();
         if (!manifest)
             fail("internal", "Could not read the Sealkeep package manifest");
         print(json ? JSON.stringify({ name: manifest.name, version: manifest.version }, null, 2) : `${manifest.name} ${manifest.version}`);
@@ -3682,7 +3690,38 @@ const HINTS = {
     // copy, if one exists, is unaffected and `sealkeep verify` proves it.
     ciphertext_integrity_failed: "the local sealed file is damaged; nothing was written. If this archive has a stored copy, `sealkeep verify` checks it and `sealkeep open <ref> <destination>` reads it back"
 };
-main().catch((error) => {
+/**
+ * One line, after the command's own output, when a newer release exists.
+ *
+ * It runs last on purpose: a person came here to do something, and an
+ * announcement that delays or replaces their answer is worse than no
+ * announcement. Anything that goes wrong here — offline, blocked registry,
+ * unreadable manifest — is silence, never an error and never an exit code.
+ * Machine-readable runs, hooks and the daemon are excluded: nothing may
+ * appear in output another program parses or in a lane nobody watches.
+ */
+async function noteNewerRelease() {
+    const command = process.argv[2];
+    const args = process.argv.slice(3);
+    if (process.argv.includes("--json") || !process.stdout.isTTY)
+        return;
+    if (command === undefined || ["hook", "daemon", "mcp", "api", "--version", "-v", "version"].includes(command))
+        return;
+    try {
+        const manifest = await ownManifest();
+        const current = manifest?.version;
+        if (!current)
+            return;
+        const dataDirFlag = args.indexOf("--data-dir");
+        const dataDir = (dataDirFlag >= 0 ? args[dataDirFlag + 1] : undefined) ?? envVar("DATA_DIR") ?? defaultDataDir();
+        const { newerReleaseThan, updateNotice } = await import("./release-check.js");
+        const latest = await newerReleaseThan(current, dataDir);
+        if (latest)
+            console.error(`\n  ${hint(updateNotice(latest, current))}\n`);
+    }
+    catch { /* a version check must never be the thing that fails */ }
+}
+main().then(noteNewerRelease, (error) => {
     const { error: payload } = errorPayload(error);
     console.error(`\n  ${mark.fail()} ${payload.message}`);
     const suggestion = HINTS[payload.code];
@@ -3690,4 +3729,5 @@ main().catch((error) => {
         console.error(`  ${hint(suggestion)}`);
     console.error(`  ${dim(payload.code)}\n`);
     process.exitCode = 1;
+    return noteNewerRelease();
 });

package/dist/src/release-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The version to suggest, or null. Never throws, never blocks longer than its
+ * own timeout, and answers from cache when today's check already happened.
+ */
+export declare function newerReleaseThan(currentVersion: string, dataDir: string, options?: {
+    now?: () => number;
+    env?: NodeJS.ProcessEnv;
+    fetchLatest?: (signal: AbortSignal) => Promise<string | null>;
+}): Promise<string | null>;
+/** The one line a person sees. Kept to a fact and the command that acts on it. */
+export declare function updateNotice(latest: string, current: string): string;

package/dist/src/release-check.js

@@ -0,0 +1,117 @@
+/**
+ * "A newer Sealkeep is out."
+ *
+ * Shipping 0.11.0 taught us why this is worth having: a release that could not
+ * open archives written by its predecessor sat on the registry for two days,
+ * and nobody running it had any way to learn that the fix existed. A person
+ * finds out from the tool they already have open, or not at all.
+ *
+ * The rules this follows, because a version check is a network call the user
+ * did not ask for:
+ *  - never before the command runs, and never in its way: the check is a
+ *    background read of a cached answer, and the note prints after the work;
+ *  - at most one request a day, per machine, recorded in the vault's runtime
+ *    directory, so a scripted loop cannot turn into a traffic generator;
+ *  - never for a machine-readable run (`--json`), a hook, or a daemon;
+ *  - silent on every failure. An offline laptop, a blocked registry and a
+ *    proxy that answers with HTML all mean "no note", never an error;
+ *  - nothing is sent but the request itself: no vault id, no identifiers, no
+ *    telemetry. It reads the same public metadata `npm view` reads, and can be
+ *    turned off for good with SEALKEEP_NO_UPDATE_CHECK=1.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+const REGISTRY_URL = "https://registry.npmjs.org/sealkeep/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60_000;
+const REQUEST_TIMEOUT_MS = 2_000;
+const statePath = (dataDir) => join(dataDir, "runtime", "latest-release.json");
+/** A dotted release, compared numerically; anything unparseable sorts lowest. */
+function isNewer(candidate, current) {
+    const parts = (value) => {
+        const core = value.split(/[-+]/, 1)[0] ?? "";
+        const numbers = core.split(".").map((piece) => Number.parseInt(piece, 10));
+        return numbers.length === 3 && numbers.every((piece) => Number.isInteger(piece) && piece >= 0) ? numbers : null;
+    };
+    const left = parts(candidate);
+    const right = parts(current);
+    if (!left || !right)
+        return false;
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] > right[index];
+    }
+    // A pre-release of the same numbers is not an upgrade to offer.
+    return false;
+}
+async function readCached(dataDir) {
+    try {
+        const raw = JSON.parse(await readFile(statePath(dataDir), "utf8"));
+        if (typeof raw.version !== "string" || typeof raw.at !== "string")
+            return null;
+        return { version: raw.version, at: raw.at };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCached(dataDir, value) {
+    const target = statePath(dataDir);
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+        await mkdir(join(dataDir, "runtime"), { recursive: true, mode: 0o700 });
+        await writeFile(temp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+        await rename(temp, target);
+    }
+    catch {
+        // A read-only or full disk must never cost a command its result.
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+async function fetchLatest(signal) {
+    try {
+        const response = await fetch(REGISTRY_URL, { signal, headers: { accept: "application/vnd.npm.install-v1+json, application/json" } });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        return typeof body.version === "string" && /^\d+\.\d+\.\d+/.test(body.version) ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The version to suggest, or null. Never throws, never blocks longer than its
+ * own timeout, and answers from cache when today's check already happened.
+ */
+export async function newerReleaseThan(currentVersion, dataDir, options = {}) {
+    const env = options.env ?? process.env;
+    if (env.SEALKEEP_NO_UPDATE_CHECK === "1" || env.NO_UPDATE_NOTIFIER === "1" || env.CI === "true")
+        return null;
+    const now = options.now ?? Date.now;
+    const cached = await readCached(dataDir);
+    const fresh = cached && now() - Date.parse(cached.at) < CHECK_INTERVAL_MS;
+    if (fresh)
+        return isNewer(cached.version, currentVersion) ? cached.version : null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let latest;
+    try {
+        latest = await (options.fetchLatest ?? fetchLatest)(controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    // A failed check is recorded as "asked today" too: an offline machine must
+    // not retry on every single command.
+    await writeCached(dataDir, { version: latest ?? cached?.version ?? currentVersion, at: new Date(now()).toISOString() });
+    if (!latest)
+        return null;
+    return isNewer(latest, currentVersion) ? latest : null;
+}
+/** The one line a person sees. Kept to a fact and the command that acts on it. */
+export function updateNotice(latest, current) {
+    return `Sealkeep ${latest} is available (you have ${current}). Update with: npm i -g sealkeep@latest`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sealkeep",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "type": "module",
   "description": "Sealkeep by SPALA AI \u2014 your AI coding-agent history, sealed, searchable, and shared across your machines.",
   "repository": {