artshelf 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -72,6 +72,21 @@
   backward-compatible audit report. The default human renders of these three
   commands now lead each ledger and summary line with a `✓`/`⚠` attention glyph
   (plain Unicode, no color) so redirected output stays clean.
+- Shortened the automatic update-check cache so no-update, failed, missing, or
+  null results expire after 1 hour while update-available results keep the
+  24-hour TTL, letting newly published releases surface sooner. `artshelf update`
+  forces a fresh latest-version check instead of trusting a stale no-update
+  cache, `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed TTL
+  (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility), and a
+  non-numeric TTL value falls back to the default instead of disabling expiry.
+
+## [0.10.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.0...artshelf-v0.10.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **cli:** shorten no-update cache TTL for update checks ([d41e49e](https://github.com/calvinnwq/artshelf/commit/d41e49e7d5da02dfaa86fb70eaa7d5e7fb3d543e))
+* **cli:** split update-check cache TTL so new releases surface sooner ([5afcfaa](https://github.com/calvinnwq/artshelf/commit/5afcfaafac4941b71f6a84c694139a64774a1d59))
 
 ## [0.10.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.9.0...artshelf-v0.10.0) (2026-06-12)
 

package/README.md

@@ -62,12 +62,14 @@ install with `npm unlink -g artshelf`.
 </details>
 
 Artshelf checks npm occasionally and prints a non-blocking notice to stderr when
-a newer published version is available. Run `artshelf update` only for npm
-global installs; it upgrades with `npm install -g artshelf@latest`. pnpm global
-installs should update with `pnpm add -g artshelf@latest`, and source installs
-still update by pulling, rebuilding, and linking the checkout. Set
-`ARTSHELF_NO_UPDATE_CHECK=1` for scheduled jobs that must avoid network and
-update-cache writes.
+a newer published version is available. Available-update results are cached for
+24 hours by default; failed, missing, or no-update results are cached for 1 hour
+so a newly published release is noticed sooner. Run `artshelf update` only for
+npm global installs; it forces a fresh latest-version check before upgrading
+with `npm install -g artshelf@latest`. pnpm global installs should update with
+`pnpm add -g artshelf@latest`, and source installs still update by pulling,
+rebuilding, and linking the checkout. Set `ARTSHELF_NO_UPDATE_CHECK=1` for
+scheduled jobs that must avoid network and update-cache writes.
 
 ### Recommended agent setup
 

package/SPEC.md

@@ -353,12 +353,17 @@ Rules:
 - Read-only command guarantees refer to ledger and artifact mutation; automatic
   update-check cache writes are separate and can be disabled.
 - Update notices must never pollute JSON stdout.
-- Automatic checks cache successful and failed latest-version lookups at
-  `~/.artshelf/update-check.json` by default, with a 24-hour TTL.
+- Automatic checks cache latest-version lookups at
+  `~/.artshelf/update-check.json` by default. Cached update-available results
+  (`latest > current`) keep the long 24-hour TTL; cached no-update, failed,
+  missing, or null results use a shorter 1-hour TTL so newly published releases
+  are noticed sooner.
 - `ARTSHELF_NO_UPDATE_CHECK=1` disables automatic checks for scheduled jobs,
   tests, and no-network environments.
 - `ARTSHELF_UPDATE_CACHE` overrides the update-cache path,
-  `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the cache TTL, and
+  `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the update-available cache TTL,
+  `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed cache TTL
+  (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility), and
   `ARTSHELF_NPM_REGISTRY_URL` overrides the npm latest-version endpoint.
 - `ARTSHELF_LATEST_VERSION` overrides the discovered latest version for tests.
 - `ARTSHELF_UPDATE_DRY_RUN=1` makes `artshelf update` report the npm command it
@@ -541,9 +546,13 @@ V1 also supports a user-level registry of known ledgers:
   overrides it for tests and controlled runs; legacy `SHELF_NOW` is read only
   when `ARTSHELF_NOW` is unset.
 - Automatic npm update checks cache their latest-version result at
-  `~/.artshelf/update-check.json` by default. `ARTSHELF_NO_UPDATE_CHECK=1`
-  disables automatic checks, `ARTSHELF_UPDATE_CACHE` overrides the cache path,
-  and `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the cache TTL.
+  `~/.artshelf/update-check.json` by default. Cached update-available results
+  use the long 24-hour TTL; cached no-update, failed, missing, or null results
+  use a shorter 1-hour TTL. `ARTSHELF_NO_UPDATE_CHECK=1` disables automatic
+  checks, `ARTSHELF_UPDATE_CACHE` overrides the cache path,
+  `ARTSHELF_UPDATE_CHECK_TTL_MS` overrides the update-available TTL, and
+  `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed TTL
+  (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility).
 - `put` registers the ledger it writes to.
 - `ledgers add` registers an existing ledger explicitly.
 - `--all` reads registered ledgers as one review surface.

package/dist/src/cli.js

@@ -9,6 +9,7 @@ const VERSION = readPackageVersion();
 const PACKAGE_NAME = "artshelf";
 const NPM_REGISTRY_URL = process.env.ARTSHELF_NPM_REGISTRY_URL ?? `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const NO_UPDATE_CHECK_TTL_MS = 60 * 60 * 1000;
 const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
@@ -1015,26 +1016,41 @@ async function getLatestVersion(options) {
     return latest;
 }
 function readUpdateCache() {
-    const ttl = Number(process.env.ARTSHELF_UPDATE_CHECK_TTL_MS ?? UPDATE_CHECK_TTL_MS);
-    if (ttl < 0)
-        return null;
     const cachePath = updateCachePath();
     if (!existsSync(cachePath))
         return null;
     try {
         const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (!("latest" in cache))
+            cache.latest = null;
         if (cache.latest !== null && typeof cache.latest !== "string")
             return null;
         if (typeof cache.checkedAt !== "number")
             return null;
+        const latest = cache.latest === null ? null : normalizeVersion(cache.latest);
+        const ttl = updateCacheTtlFor(latest);
+        if (ttl < 0)
+            return null;
         if (Date.now() - cache.checkedAt > ttl)
             return null;
-        return { latest: cache.latest === null ? null : normalizeVersion(cache.latest) };
+        return { latest };
     }
     catch {
         return null;
     }
 }
+function updateCacheTtlFor(latest) {
+    if (latest && compareVersions(latest, VERSION) > 0) {
+        return resolveTtlMs(process.env.ARTSHELF_UPDATE_CHECK_TTL_MS, UPDATE_CHECK_TTL_MS);
+    }
+    return resolveTtlMs(process.env.ARTSHELF_NO_UPDATE_CHECK_TTL_MS ?? process.env.ARTSHELF_UPDATE_CHECK_TTL_MS, NO_UPDATE_CHECK_TTL_MS);
+}
+function resolveTtlMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
 function writeUpdateCache(latest) {
     try {
         const cachePath = updateCachePath();

package/docs/reference.html

@@ -148,7 +148,10 @@ artshelf update [--json]</code></pre>
               only. pnpm global installs should update with
               <code>pnpm add -g artshelf@latest</code>. Source installs should update by
               pulling, rebuilding, and linking the checkout. Notices are cached in
-              <code>~/.artshelf/update-check.json</code>; set
+              <code>~/.artshelf/update-check.json</code>: update-available results use
+              the long 24-hour TTL, while no-update, failed, missing, or null results
+              use a shorter 1-hour TTL so newly published releases are noticed sooner.
+              <code>artshelf update</code> forces a fresh latest-version check. Set
               <code>ARTSHELF_NO_UPDATE_CHECK=1</code> to disable automatic checks for
               no-network scripts and scheduled jobs. Read-only command labels refer
               to ledger and artifact mutation, not this optional update-check cache.
@@ -261,7 +264,8 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <tr><td>ARTSHELF_NOW</td><td>override current time for retention and due calculations</td></tr>
               <tr><td>ARTSHELF_NO_UPDATE_CHECK=1</td><td>disable automatic npm update checks</td></tr>
               <tr><td>ARTSHELF_UPDATE_CACHE</td><td>override the update-check cache path</td></tr>
-              <tr><td>ARTSHELF_UPDATE_CHECK_TTL_MS</td><td>override the update-check cache TTL</td></tr>
+              <tr><td>ARTSHELF_UPDATE_CHECK_TTL_MS</td><td>override the update-available cache TTL; also acts as the no-update TTL fallback for compatibility</td></tr>
+              <tr><td>ARTSHELF_NO_UPDATE_CHECK_TTL_MS</td><td>override the no-update/failed cache TTL specifically</td></tr>
               <tr><td>ARTSHELF_NPM_REGISTRY_URL</td><td>override the npm latest-version endpoint</td></tr>
               <tr><td>ARTSHELF_UPDATE_DRY_RUN=1</td><td>print the npm update command without running it</td></tr>
               <tr><td>ARTSHELF_LATEST_VERSION</td><td>override the latest-version value for tests</td></tr>
@@ -290,7 +294,9 @@ artshelf trash purge --execute --plan-id &lt;id&gt; [--ledger &lt;path&gt;] [--j
               <code>~/.artshelf/ledgers.json</code> is the discovery index for <code>--all</code>
               review, status, cleanup dry-run, and trash-list; project records stay in their own
               repo-local ledgers. Automatic update checks cache their last npm result at
-              <code>~/.artshelf/update-check.json</code> by default.
+              <code>~/.artshelf/update-check.json</code> by default, with a long TTL
+              for update-available results and a shorter TTL for no-update or failed
+              results.
             </p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",