artshelf 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -72,6 +72,38 @@
   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.2](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.1...artshelf-v0.10.2) (2026-06-13)
+
+
+### Code Refactoring
+
+* **cli:** extract command dispatch and shared modules from the monolithic
+  entrypoint ([c198c19](https://github.com/calvinnwq/artshelf/commit/c198c194693e756dd02b2525e2f6abbee5741d59))
+* **cli:** separate status, doctor, review, and JSON renderers from command
+  orchestration ([4ec76b0](https://github.com/calvinnwq/artshelf/commit/4ec76b0b0e4f45562d0e98a1237602bc5d41ca67))
+* **cli:** extract update environment, package, path, and process adapter seams
+  ([4ec76b0](https://github.com/calvinnwq/artshelf/commit/4ec76b0b0e4f45562d0e98a1237602bc5d41ca67))
+* **cli:** restore real per-command modules, add the validate command module,
+  and strengthen architecture guardrails
+  ([a617ba3](https://github.com/calvinnwq/artshelf/commit/a617ba36e7de7d8a5725d1ba47eb3419ae3c6329))
+* **cli:** move help rendering out of the entrypoint and into shared help text
+  ([8e2698b](https://github.com/calvinnwq/artshelf/commit/8e2698bce1b47073d434113cbe1e8cfb32ec34e2))
+
+## [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

@@ -261,7 +261,7 @@ the next action always points at an explicit follow-up command.
 
 `review`, `status`, and `doctor` share three render modes. The default human
 render leads each ledger and summary line with a `✓`/`⚠` attention glyph; `--json`
-stays the full, backward-compatible audit report; and `--agent` emits a compact,
+stays the full, backward-compatible public audit report; and `--agent` emits a compact,
 deterministic single-line JSON decision packet for agents, taking precedence over
 `--json` when both are passed. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
@@ -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/adapters/process.js

@@ -0,0 +1,7 @@
+import { spawnSync } from "node:child_process";
+export function installGlobalNpmPackage(packageSpec, mode) {
+    if (mode === "pipe") {
+        return spawnSync("npm", ["install", "-g", packageSpec], { encoding: "utf8" });
+    }
+    return spawnSync("npm", ["install", "-g", packageSpec], { encoding: "utf8", stdio: "inherit" });
+}

package/dist/src/adapters/update.js

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { latestVersionOverride, noUpdateCheckTtlMs, updateCheckTtlMs } from "../config/env.js";
+import { NO_UPDATE_CHECK_TTL_MS, UPDATE_CHECK_TTL_MS, VERSION, npmRegistryUrl } from "../config/package.js";
+import { updateCachePath } from "../config/paths.js";
+export async function getUpdateInfo(options) {
+    return createDefaultUpdateAdapter().getUpdateInfo(options);
+}
+export function createUpdateAdapter(options) {
+    async function getUpdateInfo(optionsForCheck) {
+        const latest = await getLatestVersion(optionsForCheck);
+        if (!latest)
+            return null;
+        return {
+            current: options.currentVersion,
+            latest,
+            updateAvailable: compareVersions(latest, options.currentVersion) > 0
+        };
+    }
+    async function getLatestVersion(optionsForCheck) {
+        const override = latestVersionOverride(options.env);
+        if (override)
+            return normalizeVersion(override);
+        if (!optionsForCheck.force) {
+            const cached = readUpdateCache();
+            if (cached)
+                return cached.latest;
+        }
+        const latest = await options.fetchLatestVersion(options.registryUrl);
+        writeUpdateCache(latest);
+        return latest;
+    }
+    function readUpdateCache() {
+        const cachePath = options.cachePath();
+        if (!options.fileExists(cachePath))
+            return null;
+        try {
+            const cache = JSON.parse(options.readTextFile(cachePath));
+            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 (options.now() - cache.checkedAt > ttl)
+                return null;
+            return { latest };
+        }
+        catch {
+            return null;
+        }
+    }
+    function updateCacheTtlFor(latest) {
+        if (latest && compareVersions(latest, options.currentVersion) > 0) {
+            return updateCheckTtlMs(options.env, UPDATE_CHECK_TTL_MS);
+        }
+        return noUpdateCheckTtlMs(options.env, NO_UPDATE_CHECK_TTL_MS);
+    }
+    function writeUpdateCache(latest) {
+        try {
+            const cachePath = options.cachePath();
+            const dir = dirname(cachePath);
+            if (dir) {
+                options.ensureDirectory(dir);
+                options.writeTextFile(cachePath, `${JSON.stringify({ latest, checkedAt: options.now() }, null, 2)}\n`);
+            }
+        }
+        catch {
+            // Update checks should never affect normal CLI behavior.
+        }
+    }
+    return { getUpdateInfo };
+}
+function createDefaultUpdateAdapter() {
+    const registryUrl = npmRegistryUrl();
+    return createUpdateAdapter({
+        currentVersion: VERSION,
+        registryUrl,
+        env: process.env,
+        now: () => Date.now(),
+        cachePath: () => updateCachePath(),
+        fileExists: existsSync,
+        readTextFile: (path) => readFileSync(path, "utf8"),
+        writeTextFile: writeFileSync,
+        ensureDirectory: (path) => mkdirSync(path, { recursive: true }),
+        fetchLatestVersion: (url) => fetchLatestNpmVersion(url)
+    });
+}
+async function fetchLatestNpmVersion(registryUrl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 750);
+    try {
+        const response = await fetch(registryUrl, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": `artshelf/${VERSION}` }
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (!body || typeof body !== "object" || typeof body.version !== "string")
+            return null;
+        return normalizeVersion(body.version);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/i, "");
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < Math.max(a.numbers.length, b.numbers.length); index += 1) {
+        const diff = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function parseVersion(version) {
+    const [main = "", prerelease = ""] = normalizeVersion(version).split("-", 2);
+    return {
+        numbers: main.split(".").map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }),
+        prerelease
+    };
+}