sprag-cli 3.44.0 → 3.46.0

package/src/update-check.js

@@ -10,7 +10,16 @@
  *
  * State lives next to the other user-data files:
  *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
- *     dismissedVersion: "3.25.0"|undefined }
+ *     dismissedVersion: "3.25.0"|undefined,
+ *     highlights: ["…", "…"]|undefined, highlightsFor: "3.25.0"|undefined }
+ *
+ * `highlights` is what the new version actually adds, read from the GitHub
+ * release for that tag. A bare "v3.24 → v3.25 is available" gives the user
+ * nothing to weigh: the answer to "should I upgrade" is in what changed, and
+ * asking them to go find that themselves is how an upgrade notice becomes
+ * something to dismiss. The release body is fetched on the same detached,
+ * once-a-day pass as the version check, and its absence never blocks the
+ * notice — a version number alone is still worth saying.
  *
  * Opt out with CTS_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER (the de-facto
  * standard env var — anyone who set it for other CLIs meant us too).
@@ -102,6 +111,9 @@ export function updateStatus(currentVersion) {
     // means "ask me again in five minutes", forever.
     dismissed: available && s.dismissedVersion === latest,
     stale: age >= CHECK_INTERVAL_MS,
+    // Only when they describe THIS version. A cache written for an earlier
+    // release would otherwise sell the wrong upgrade.
+    highlights: Array.isArray(s.highlights) && s.highlightsFor === latest ? s.highlights : [],
   };
 }
 
@@ -143,6 +155,116 @@ export function cliEntryPath() {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
 }
 
+// Release notes come from the repository's own releases, because the registry
+// does not carry them: `/latest` answers with package metadata and no changelog
+// of any kind. Unauthenticated reads are allowed at 60/hour, and this runs once
+// a day behind the same interval as the version check, so the budget is ample.
+const RELEASES_API = 'https://api.github.com/repos/rootstudioyaml/sprag/releases/tags';
+const MAX_HIGHLIGHTS = 3;
+const MAX_HIGHLIGHT_LEN = 110;
+
+/**
+ * The headline items of a release body, as short single lines.
+ *
+ * Release notes are written for people reading a web page: headings, prose
+ * paragraphs, links, and bold runs. A session-start notice has one line per
+ * item and no room for any of that, so this keeps only what reads as an item
+ * of a list and strips it to plain text. Anything that survives is a sentence
+ * the user can judge an upgrade by; anything that does not is left behind
+ * rather than truncated into nonsense.
+ *
+ * @param {string} body - the release body as published
+ * @returns {string[]} at most MAX_HIGHLIGHTS lines, or [] when nothing fits
+ */
+export function releaseHighlights(body) {
+  const text = String(body || '');
+  if (!text.trim()) return [];
+  const out = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    // Bullets only. A heading names a section, and a prose paragraph in a
+    // release body is usually the rationale rather than the change itself.
+    const m = /^[-*+]\s+(.*)$/.exec(line);
+    if (!m) continue;
+    // Markup goes first, so the sentence split below sees the text a reader
+    // would: `**Bash writes are checked.**` is one sentence, not a bold run.
+    // One exception has to be caught before that: a stop followed straight by a
+    // code span (`…checked.\`install\` migrates…`) is a sentence boundary, and
+    // stripping the backtick first leaves a lowercase letter the split ignores.
+    // A space there is what the author meant, and it costs nothing if not.
+    let item = m[1]
+      .replace(/([.。])(`)/g, '$1 $2')
+      .replace(/`([^`]*)`/g, '$1')            // code spans read fine as plain text
+      .replace(/\*\*([^*]*)\*\*/g, '$1')      // bold
+      .replace(/\*([^*]*)\*/g, '$1')          // italics
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links keep their label
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (!item) continue;
+    // Release notes lead with the change and follow with the reasoning, often
+    // for several sentences. The first sentence is the change, so that is what
+    // a one-line notice keeps — cutting at a character count instead lands
+    // mid-clause and reads as a broken string rather than a short one.
+    //
+    // The break does not require a space after the stop: "…checked.The matcher…"
+    // is a typo a release body can carry, and requiring one there merged the two
+    // sentences into a single over-long line. A capital letter or a Hangul
+    // syllable directly after the stop is enough to say a new sentence started;
+    // a digit is not, so "0.5s" and "v3.45.0" stay intact.
+    //
+    // Abbreviations are excluded by name. "Fixed e.g. the matcher" would
+    // otherwise end after two words, which is worse than a long line: it reads
+    // as a complete thought and is not one. This list covers what actually turns
+    // up in release prose rather than trying to be exhaustive.
+    // `etc.` is deliberately absent: it ends a sentence as often as it continues
+    // one, so either choice is wrong half the time and the wrong one here merges
+    // two sentences rather than truncating one. Merging is the milder failure,
+    // and the length cap below bounds it.
+    const ABBREV = /\b(?:e\.g|i\.e|vs|cf|Dr|Mr|Ms|St|approx|no)\.$/i;
+    const parts = item.split(/(?<=[.。])(?:\s+|(?=[A-Z가-힣]))/);
+    let first = parts[0];
+    for (let k = 1; k < parts.length && ABBREV.test(first); k += 1) {
+      // The stop belonged to an abbreviation, so the sentence continues.
+      first = `${first} ${parts[k]}`;
+    }
+    item = first || item;
+    // Some first sentences are themselves a paragraph. Those get cut, but at a
+    // word boundary and with the ellipsis that says so.
+    if (item.length > MAX_HIGHLIGHT_LEN) {
+      const cut = item.slice(0, MAX_HIGHLIGHT_LEN);
+      const space = cut.lastIndexOf(' ');
+      item = (space > 40 ? cut.slice(0, space) : cut).replace(/[,;:—\-]$/, '').trim() + '…';
+    }
+    out.push(item);
+    if (out.length >= MAX_HIGHLIGHTS) break;
+  }
+  return out;
+}
+
+/**
+ * Fetch the highlights for one version. Returns [] on any failure: the notice
+ * is worth showing with a bare version number, so a missing release, a rate
+ * limit, or an offline machine must not cost the user the notice itself.
+ */
+export async function fetchHighlights(version, { timeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${RELEASES_API}/v${version}`, {
+      signal: controller.signal,
+      headers: { accept: 'application/vnd.github+json' },
+    });
+    if (!res.ok) throw new Error(`releases responded ${res.status}`);
+    const body = await res.json();
+    return releaseHighlights(body && body.body);
+  } catch (e) {
+    debug('update-check:highlights', e);
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Actually hit the registry and persist the answer. Only the detached child
  * and the explicit `update-check --refresh` command call this.
@@ -168,6 +290,21 @@ export async function refreshUpdateState(currentVersion) {
     if (prev.dismissedVersion && isNewer(latest, prev.dismissedVersion)) {
       delete next.dismissedVersion;
     }
+    // What the new version adds, so the notice can answer "why would I".
+    // Only worth a second request when there is actually an upgrade to describe,
+    // and only when we do not already hold the notes for that exact version.
+    if (isNewer(latest, currentVersion) && prev.highlightsFor !== latest) {
+      const highlights = await fetchHighlights(latest);
+      if (highlights.length) {
+        next.highlights = highlights;
+        next.highlightsFor = latest;
+      } else {
+        // Drop notes belonging to an older version rather than showing them
+        // against this one.
+        delete next.highlights;
+        delete next.highlightsFor;
+      }
+    }
     writeUpdateState(next);
     return { ok: true, latest };
   } catch (e) {

package/src/window-labels.js

@@ -1,5 +1,9 @@
 /**
- * Friendly labels + icons for `rate_limits.*` keys from Claude Code's stdin
+ * Friendly labels + icons for `rate_limits.*` keys from Claude Code's stdin.
+ *
+ * Each window carries two glyphs. `icon` is the emoji; `narrowIcon` is the
+ * one-cell glyph used where emoji garble the line, chosen by JetBrains Mono
+ * coverage for the reason src/glyphs.js explains.
  * payload. Known keys (`five_hour`, `seven_day`) get curated short/long labels
  * and dedicated icons. Unknown keys are passed through with a derived label so
  * any future window Anthropic adds (e.g. `seven_day_sonnet`) renders without
@@ -17,15 +21,21 @@ const KNOWN = {
   // 'current' mirrors how `weekly` reads next to 7D — names the window in
   // plain English so a glance at `✦ current ████▒░ 72%` tells the eye what's
   // being measured without parsing the icon's meaning.
-  five_hour: { short: '5H', long: 'Current session', icon: '✦', usageLabel: 'current' },
-  seven_day: { short: '7D', long: 'Current week', icon: '📅', usageLabel: 'weekly' },
+  five_hour: { short: '5H', long: 'Current session', icon: '✦', narrowIcon: '✶', usageLabel: 'current' },
+  seven_day: { short: '7D', long: 'Current week', icon: '📅', narrowIcon: '⌸', usageLabel: 'weekly' },
   // Speculative — `/usage` shows a Sonnet-only weekly bucket, so if Anthropic
   // ever surfaces it on stdin we render with a sensible default already.
-  seven_day_sonnet: { short: '7D-S', long: 'Current week (Sonnet)', icon: '🅂', usageLabel: 'weekly (Sonnet)' },
-  seven_day_opus: { short: '7D-O', long: 'Current week (Opus)', icon: '🅾', usageLabel: 'weekly (Opus)' },
+  seven_day_sonnet: { short: '7D-S', long: 'Current week (Sonnet)', icon: '🅂', narrowIcon: '◇', usageLabel: 'weekly (Sonnet)' },
+  seven_day_opus: { short: '7D-O', long: 'Current week (Opus)', icon: '🅾', narrowIcon: '◆', usageLabel: 'weekly (Opus)' },
+  // 💳 는 지출 한도를 가리킨다. 이전에 쓰던 🔑 은 인증 수단을 연상시키므로,
+  // 이 칩이 새로 보는 사람에게 키 자신의 상태로 읽힐 여지가 있었다.
   // LiteLLM 게이트웨이 키 예산. rate_limits 가 없는 환경에서 cap 게이지를
   // 대신하는 합성 윈도우라서, 여기 라벨만 있으면 나머지 렌더는 공용 경로를 탄다.
-  litellm_budget: { short: 'BUDGET', long: 'LiteLLM key budget', icon: '🔑', usageLabel: 'budget' },
+  litellm_budget: {
+    short: 'BUDGET', long: 'LiteLLM key budget', icon: '💳', narrowIcon: '◫', usageLabel: 'budget',
+    // Budgets reset on a billing cycle, so "in 3d 4h" beats a bare weekday.
+    resetStyle: 'countdown',
+  },
 };
 
 function deriveShort(key) {
@@ -60,5 +70,5 @@ function deriveLong(key) {
 export function labelForKey(key) {
   if (KNOWN[key]) return KNOWN[key];
   const short = deriveShort(key);
-  return { short, long: deriveLong(key), icon: '⏱', usageLabel: short };
+  return { short, long: deriveLong(key), icon: '⏱', narrowIcon: '◕', usageLabel: short };
 }