@kud/gh-ink 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -48,6 +48,44 @@ interface InboxExtension {
     body: (onExit: () => void, target?: ExtensionTarget) => ReactNode;
 }
 
+/**
+ * What the last fetch cost and what was left afterwards, as reported INSIDE the
+ * query response by `rateLimit { cost remaining resetAt }`.
+ *
+ * Cached because the budget is shared by every instance and every other tool on
+ * the account, so the useful reading is the most recent one from anywhere — not
+ * whatever this process happens to remember. A cockpit launching cold needs it
+ * BEFORE its first fetch, which is the one moment it has no response to read it
+ * from.
+ *
+ * Never from `GET /rate_limit`. That endpoint is served from replicas that do
+ * not share state: on 2026-08-27 it reported `used: 0, remaining: 5000` while
+ * GraphQL was refusing every call, returned a `reset` exactly 3600s ahead of
+ * each read, and gave `used` values that DECREASED between two calls a second
+ * apart. This figure comes from the service that enforces the limit, in the same
+ * response as the data, so it cannot disagree with itself.
+ */
+type InboxBudget = {
+    /** Points left in the window. */
+    remaining: number;
+    /** What the query just cost, so a caller can price the next one. */
+    cost: number;
+    /** ISO-8601, from GitHub rather than computed locally. */
+    resetAt: string;
+};
+type CachedCockpit = {
+    sections: Section[];
+    login: string;
+    at: number;
+    budget?: InboxBudget;
+};
+declare const readCache: (key: string) => CachedCockpit | null;
+declare const writeCache: (key: string, data: {
+    sections: Section[];
+    login: string;
+    budget?: InboxBudget;
+}) => void;
+
 type GHDetail = {
     reviewDecision?: string;
     mergeable?: string;
@@ -238,6 +276,21 @@ declare const filterByRepos: (sections: Section[], repos: Set<string>) => Sectio
 declare const withoutItem: (sections: Section[], target: GHItem) => Section[];
 declare const reposInSections: (sections: Section[]) => string[];
 declare const moveCursor: (items: AnyItem[], current: number, dir: 1 | -1) => number;
+/**
+ * What to say about the remaining budget, or nothing at all.
+ *
+ * Priced in whole fetches because that is the unit that runs out: the query
+ * costs ~111 points against a 5,000 pool, so "some points left" and "another
+ * fetch left" are different questions and only the second one is actionable.
+ *
+ * Silent above the threshold. A counter on a healthy account is noise in a
+ * header already carrying four things, and noise is what gets skimmed past on
+ * the one day it matters.
+ */
+declare const budgetNotice: (budget: InboxBudget | null | undefined, now?: number) => {
+    label: string;
+    critical: boolean;
+} | null;
 /**
  * Whether this row draws a blank line above it.
  *
@@ -320,6 +373,13 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
         sections: Section[];
         login: string;
         ciStatus?: CiStatus | null;
+        /**
+         * What that fetch cost and what is left, if the host's query asked. GitHub
+         * answers `rateLimit { cost remaining resetAt }` inside the response for
+         * free, so a host that asks pays nothing to know — and an inbox that knows
+         * can decline to spend the last of it on a refresh nobody requested.
+         */
+        budget?: InboxBudget;
     }>;
     cacheKey?: string;
     title?: string;
@@ -355,17 +415,6 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
     extensions?: InboxExtension[];
 }) => React.JSX.Element;
 
-type CachedCockpit = {
-    sections: Section[];
-    login: string;
-    at: number;
-};
-declare const readCache: (key: string) => CachedCockpit | null;
-declare const writeCache: (key: string, data: {
-    sections: Section[];
-    login: string;
-}) => void;
-
 /**
  * A named slice of the reader's repos. Two or more turn on the in-app toggle;
  * one or none means an undivided set and no toggle at all.
@@ -453,4 +502,4 @@ declare const matchesFilter: (repo: string, filter: RepoFilter) => boolean;
  */
 declare const parsePatterns: (value: string) => string[];
 
-export { type Action, ActionMenu, type AnyItem, App, COLS, type CiStatus, CiStatusLine, type CiStatusState, CommentsPanel, type CommentsPanelProps, type DetailContext, type ExplainSection, type ExtensionTarget, type GHDetail, type GHItem, HealthPanel, type HealthPanelProps, type InboxConfig, type InboxExtension, type JiraTransition, type OriginSplit, type RepoFilter, type RepoHeader, type RepoProfile, type Section, type ShowLess, type ShowMore, type Standing, type SubgroupHeader, type TaskRow, buildActions, buildCheckoutCmd, checkoutDirs, clipboard, configureInbox, drillCmd, explainGhAction, explainItem, filterByOrigin, filterByRepos, filterBySearch, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, inboxConfig, insertRepoHeaders, itermRun, jumpToRepo, jumpToRepoPane, layoutGHItems, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, profileOf, readCache, relativeTime, renderMarkdown, repoPriority, reposInSections, resetInboxConfig, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, sortByRecency, sortItems, toCiStatusState, topLevelCount, truncate, useActionMenu, whoseMove, windowCount, withHeaders, withoutItem, writeCache };
+export { type Action, ActionMenu, type AnyItem, App, COLS, type CiStatus, CiStatusLine, type CiStatusState, CommentsPanel, type CommentsPanelProps, type DetailContext, type ExplainSection, type ExtensionTarget, type GHDetail, type GHItem, HealthPanel, type HealthPanelProps, type InboxBudget, type InboxConfig, type InboxExtension, type JiraTransition, type OriginSplit, type RepoFilter, type RepoHeader, type RepoProfile, type Section, type ShowLess, type ShowMore, type Standing, type SubgroupHeader, type TaskRow, budgetNotice, buildActions, buildCheckoutCmd, checkoutDirs, clipboard, configureInbox, drillCmd, explainGhAction, explainItem, filterByOrigin, filterByRepos, filterBySearch, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, inboxConfig, insertRepoHeaders, itermRun, jumpToRepo, jumpToRepoPane, layoutGHItems, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, profileOf, readCache, relativeTime, renderMarkdown, repoPriority, reposInSections, resetInboxConfig, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, sortByRecency, sortItems, toCiStatusState, topLevelCount, truncate, useActionMenu, whoseMove, windowCount, withHeaders, withoutItem, writeCache };

package/dist/index.js

@@ -632,7 +632,7 @@ var checkoutDirs = () => [
 
 // src/inbox/cache.ts
 var cacheTtlMs = () => inboxConfig().cacheTtlMs;
-var CACHE_VERSION = 2;
+var CACHE_VERSION = 3;
 var cacheDir = () => join(
   process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
   inboxConfig().cacheNamespace
@@ -643,7 +643,12 @@ var readCache = (key) => {
     const raw = JSON.parse(readFileSync(cacheFile(key), "utf8"));
     if (raw?.version !== CACHE_VERSION) return null;
     if (!Array.isArray(raw?.sections)) return null;
-    return { sections: raw.sections, login: raw.login ?? "", at: raw.at ?? 0 };
+    return {
+      sections: raw.sections,
+      login: raw.login ?? "",
+      at: raw.at ?? 0,
+      budget: raw.budget
+    };
   } catch {
     return null;
   }
@@ -1048,6 +1053,18 @@ var moveCursor = (items, current2, dir) => {
   if (next < 0 || next >= items.length) return current2;
   return next;
 };
+var budgetNotice = (budget, now = Date.now()) => {
+  if (!budget) return null;
+  if (new Date(budget.resetAt).getTime() <= now) return null;
+  const per = Math.max(budget.cost, 1);
+  const fetches = Math.floor(budget.remaining / per);
+  if (fetches > 8) return null;
+  const mins = Math.max(
+    1,
+    Math.round((new Date(budget.resetAt).getTime() - now) / 6e4)
+  );
+  return fetches <= 0 ? { label: `\u26A1 API budget spent \xB7 ${mins}m`, critical: true } : { label: `\u26A1 ${fetches} fetch${fetches === 1 ? "" : "es"} left`, critical: false };
+};
 var gapsAbove = (items, i) => {
   const item = items[i];
   if (!item || i === 0) return false;
@@ -1626,6 +1643,8 @@ var InboxHeader = ({
   login,
   brand,
   scopeLabel,
+  budgetLabel,
+  budgetCritical,
   loading,
   quiet,
   refreshing,
@@ -1637,17 +1656,19 @@ var InboxHeader = ({
   const countSeg = loading ? "      loading\u2026  " : quiet ? "  " : `  ${String(total).padStart(3)} item${total !== 1 ? "s" : ""}  \xB7  `;
   const userSeg = loading || quiet ? "" : `@${login}  `;
   const workLabel = scopeLabel ? `  ${scopeLabel}  ` : "";
+  const budgetSeg = budgetLabel ? budgetLabel + "  " : "";
   const [statusText, statusColor] = hasPending ? [`\u25CF ${pendingSummary || "new"} \xB7 r apply`, "#FF8700"] : refreshing ? ["\u21BB refreshing\u2026", "cyan"] : fetchedAt ? [`updated ${agoText(fetchedAt)}`, void 0] : ["", void 0];
   const statusSeg = statusText ? statusText + "  " : "";
   const fill = Math.max(
     4,
-    COLS - brand.length - countSeg.length - userSeg.length - workLabel.length - statusSeg.length
+    COLS - brand.length - countSeg.length - userSeg.length - workLabel.length - budgetSeg.length - statusSeg.length
   );
   return /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
     /* @__PURE__ */ jsx(Text2, { color: "#FF8700", bold: true, children: brand }),
     /* @__PURE__ */ jsx(Text2, { dimColor: true, children: countSeg }),
     userSeg ? /* @__PURE__ */ jsx(Text2, { children: userSeg }) : null,
     scopeLabel ? /* @__PURE__ */ jsx(Text2, { dimColor: true, children: workLabel }) : null,
+    budgetLabel ? /* @__PURE__ */ jsx(Text2, { bold: true, color: budgetCritical ? "#FF5F5F" : "#FF8700", children: budgetSeg }) : null,
     statusText ? /* @__PURE__ */ jsx(
       Text2,
       {
@@ -2152,6 +2173,8 @@ var BrowseScreen = ({
   ciJob,
   tabHelp,
   origin,
+  budget,
+  skippedForBudget,
   brand,
   mergedUrls,
   transients,
@@ -2611,6 +2634,8 @@ var BrowseScreen = ({
             sections: localSections,
             login,
             scopeLabel: origin?.label,
+            budgetLabel: budgetNotice(budget)?.label,
+            budgetCritical: budgetNotice(budget)?.critical,
             refreshing,
             hasPending,
             pendingSummary,
@@ -2618,6 +2643,10 @@ var BrowseScreen = ({
           }
         ),
         ciStatusState ? /* @__PURE__ */ jsx(CiStatusLine, { state: ciStatusState, job: ciJob }) : null,
+        skippedForBudget ? /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
+          /* @__PURE__ */ jsx(Text2, { bold: true, color: "#FF8700", children: "  \u26A1 auto-refresh paused to save API budget" }),
+          /* @__PURE__ */ jsx(Text2, { dimColor: true, children: "   r refreshes anyway" })
+        ] }) : null,
         /* @__PURE__ */ jsx(Box, { marginBottom: 1, children: /* @__PURE__ */ jsx(
           Tabs,
           {
@@ -2816,9 +2845,21 @@ var App = ({
     ) : "",
     [pending]
   );
+  const canAffordAuto = () => {
+    const known = budget ?? (cacheKey ? readCache(cacheKey)?.budget : null);
+    if (!known) return true;
+    if (new Date(known.resetAt).getTime() <= Date.now()) return true;
+    return known.remaining >= Math.max(known.cost, 1) * 2;
+  };
   const revalidate = (manual = false) => {
+    if (!manual && !canAffordAuto()) {
+      setSkippedForBudget(true);
+      return;
+    }
+    setSkippedForBudget(false);
     if (manual) setRefreshing(true);
     fetcher().then((fresh) => {
+      if (fresh.budget) setBudget(fresh.budget);
       if (cacheKey) writeCache(cacheKey, fresh);
       setRefreshing(false);
       setFetchedAt(Date.now());
@@ -2929,6 +2970,10 @@ var App = ({
       watcher.close();
     };
   }, [watchPath, watchDebounceMs]);
+  const [budget, setBudget] = useState(
+    () => cacheKey ? readCache(cacheKey)?.budget ?? null : null
+  );
+  const [skippedForBudget, setSkippedForBudget] = useState(false);
   const [mergedUrls, setMergedUrls] = useState([]);
   const mergeTimers = useRef([]);
   useEffect(() => () => mergeTimers.current.forEach(clearTimeout), []);
@@ -3009,6 +3054,8 @@ var App = ({
         fetchedAt,
         refreshError: refreshError ?? void 0,
         origin,
+        budget,
+        skippedForBudget,
         hidden: overlay !== null,
         mergedUrls,
         transients,
@@ -3065,4 +3112,4 @@ var matchesFilter = (repo, filter) => {
 };
 var parsePatterns = (value) => value.split(",").map((p) => p.trim()).filter(Boolean);
 
-export { ActionMenu, App, COLS, CiStatusLine, CommentsPanel, HealthPanel, buildActions, buildCheckoutCmd, checkoutDirs, clipboard, configureInbox, drillCmd, explainGhAction, explainItem, filterByOrigin, filterByRepos, filterBySearch, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, inboxConfig, insertRepoHeaders, itermRun, jumpToRepo, jumpToRepoPane, layoutGHItems, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, profileOf, readCache, relativeTime, renderMarkdown, repoPriority, reposInSections, resetInboxConfig, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, sortByRecency, sortItems, toCiStatusState, topLevelCount, truncate, useActionMenu, whoseMove, windowCount, withHeaders, withoutItem, writeCache };
+export { ActionMenu, App, COLS, CiStatusLine, CommentsPanel, HealthPanel, budgetNotice, buildActions, buildCheckoutCmd, checkoutDirs, clipboard, configureInbox, drillCmd, explainGhAction, explainItem, filterByOrigin, filterByRepos, filterBySearch, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, inboxConfig, insertRepoHeaders, itermRun, jumpToRepo, jumpToRepoPane, layoutGHItems, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, profileOf, readCache, relativeTime, renderMarkdown, repoPriority, reposInSections, resetInboxConfig, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, sortByRecency, sortItems, toCiStatusState, topLevelCount, truncate, useActionMenu, whoseMove, windowCount, withHeaders, withoutItem, writeCache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/gh-ink",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Ink components for rendering GitHub PR review comments and health — controlled, presentation-only, built on @kud/ink-ui and fed by @kud/gh.",
   "type": "module",
   "main": "dist/index.js",
@@ -48,7 +48,7 @@
     "react": ">=19"
   },
   "dependencies": {
-    "@kud/gh": "0.5.1",
+    "@kud/gh": "0.6.0",
     "@kud/ink-ui": "0.14.0",
     "zx": "8.8.5"
   },