dsh-git-badge 0.16.1 → 0.17.1

package/lib/index.js

@@ -44,7 +44,7 @@
  *       on the first refresh after each TTL window. `GIT_TERMINAL_PROMPT=0`, the
  *       shared timeout and the TTL bound keep an offline or slow remote harmless;
  *       on failure the stale-ref answer simply stands.
- *     - `detail=1` adds one `log -3` plus a stash count, and `pr=1` adds the
+ *     - `detail=1` adds a `log -10` plus a stash count, and `pr=1` adds the
  *       branch's GitHub PR/CI state read through the user's own `gh` CLI. Both
  *       serve the input chip only — the hover card and the PR token — so a
  *       sidebar row refresh pays for neither. The PR read is TTL-bounded and
@@ -95,17 +95,10 @@ const config = {
 	fetchTimeoutMs: 8000,
 	/** minimum interval between background fetches per toplevel */
 	fetchTtlMs: 60000,
+	/** how long a resolved default-branch name is trusted (per toplevel) */
+	defaultBranchTtlMs: 60000,
 	/** fs-event burst collapse window */
 	debounceMs: 200,
-	/**
-	 * Coalescing window for identical status reads. 0 (the default) collapses only
-	 * CONCURRENT identical reads — which is exactly what a burst of sidebar
-	 * session rows mounting together produces — and leaves sequential reads
-	 * honest, so a caller that mutates a repository and asks again always sees the
-	 * new state. Raise it to also absorb serial bursts, at the cost of serving a
-	 * change up to that many milliseconds late.
-	 */
-	statusCacheMs: 0,
 	/** backoff before re-attempting a failed watcher (or a missing .git) */
 	watchRetryMs: 60000,
 	/**
@@ -130,8 +123,16 @@ const config = {
 	 * process — see the PR region.
 	 */
 	prStatus: "auto",
-	/** minimum interval between forge refreshes per repository */
-	prTtlMs: 90000,
+	/**
+	 * Minimum interval between forge refreshes per repository. It must stay BELOW
+	 * the client's idle poll (FALLBACK_POLL_MS, 60s in lib/client.js): the refresh
+	 * is request-driven, so a TTL longer than that poll silently suppresses every
+	 * OTHER request — and a pull request that appears on the forge with no local
+	 * git event to announce it then waits out TTL + poll before it shows. At 90s
+	 * that worst case was ~2.5 minutes; 20s bounds it at roughly one poll, for up
+	 * to one `gh pr view` per open chip per minute.
+	 */
+	prTtlMs: 20000,
 	/**
 	 * Forge call budget. Unlike git this is a network round trip to GitHub, so
 	 * it gets a more generous budget than the status sample — but it is bounded
@@ -199,6 +200,41 @@ function runGit(dir, args, opts) {
 /** Marker response for a git invocation that failed or timed out (transient). */
 const GIT_DEGRADED = { git: false, error: "git unavailable (timeout or failure)" };
 
+/**
+ * One in-flight run per key, with optional TTL rate-limiting — the shape every
+ * cache in this half needs, written once. A caller that arrives while a run is
+ * in flight shares its promise instead of stampeding, and one whose record is
+ * fresher than `ttlMs` is served from the record instead of starting a new
+ * run. The store maps key -> { lastAttemptAt, inFlight, value }: `value` is
+ * the last settled answer, kept only when `keepValue` so a lapsed caller can
+ * be served the PREVIOUS answer while a refresh runs; `run(record)` receives
+ * the record (its `value` is that previous answer) and resolves to the next
+ * one. TTL-less stores drop the record when the run settles; a failed run is
+ * not remembered except as a TTL'd store's attempt time, which rate-limits
+ * the retry. `serve` decides what a busy-or-fresh call returns (default: the
+ * in-flight promise, or the kept value).
+ */
+function singleFlight(store, key, { ttlMs = 0, keepValue = false, serve }, run) {
+	const previous = store.get(key);
+	if (previous !== void 0 && (previous.inFlight !== null || Date.now() - previous.lastAttemptAt < ttlMs)) {
+		return serve !== void 0 ? serve(previous) : keepValue ? previous.value : previous.inFlight;
+	}
+	const record = { lastAttemptAt: Date.now(), inFlight: null, value: keepValue ? previous?.value : void 0 };
+	record.inFlight = (async () => {
+		try {
+			const value = await run(record);
+			if (keepValue) record.value = value;
+			return value;
+		} finally {
+			record.lastAttemptAt = Date.now();
+			record.inFlight = null;
+			if (ttlMs === 0) store.delete(key);
+		}
+	})();
+	store.set(key, record);
+	return keepValue ? record.value : record.inFlight;
+}
+
 //#region TTL-bounded background fetch
 /**
  * ahead/behind come from the local remote-tracking ref, which only moves on
@@ -210,6 +246,30 @@ const GIT_DEGRADED = { git: false, error: "git unavailable (timeout or failure)"
  * auto-fetch), with a TTL rather than a timer: fetch only happens when
  * someone is actually looking at the badge.
  */
+/**
+ * toplevel -> { at, value } for the repository's default branch name ("main"),
+ * resolved from `refs/remotes/origin/HEAD`. Read on the HOT path and refreshed
+ * out of band, exactly like the fetch: a status call must never pay a process
+ * for it, so the first request after a cache miss simply answers without the
+ * flag and the next one carries it.
+ */
+const defaultBranchState = new Map();
+
+/** The cached default branch, kicking a refresh when stale. Never throws. */
+function defaultBranchFor(toplevel, notify) {
+	return singleFlight(defaultBranchState, toplevel, {
+		ttlMs: config.defaultBranchTtlMs,
+		keepValue: true,
+		serve: (state) => state.value
+	}, async (record) => {
+		const out = await runGit(toplevel, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+		const name = out.stdout === null ? "" : out.stdout.trim().replace(/^origin\//u, "");
+		const value = name === "" ? void 0 : name;
+		if (record.value !== value) notify?.();
+		return value;
+	});
+}
+
 /** lastFetchAt per toplevel; in-flight promise per toplevel collapses races. */
 const fetchState = new Map();
 
@@ -221,13 +281,12 @@ const fetchState = new Map();
  * means concurrent requests share one fetch instead of stampeding.
  */
 async function maybeFetch(toplevel) {
-	const now = Date.now();
-	const state = fetchState.get(toplevel);
-	if (state !== void 0) {
-		if (state.inFlight !== null) return state.inFlight;
-		if (now - state.lastAttemptAt < config.fetchTtlMs) return false;
-	}
-	const inFlight = (async () => {
+	return singleFlight(fetchState, toplevel, {
+		ttlMs: config.fetchTtlMs,
+		// a lapsed-but-idle caller is served "nothing fetched"; only an in-flight
+		// fetch is worth sharing
+		serve: (state) => (state.inFlight ?? false)
+	}, async () => {
 		// --no-tags --prune: refs-only refresh, cheapest correct form.
 		// No remote name: `git fetch` uses the branch's configured upstream,
 		// and a bare `fetch --all` would probe every remote for every badge.
@@ -239,13 +298,8 @@ async function maybeFetch(toplevel) {
 			// route latency, paid at most once per fetchTtlMs per workspace.
 			timeout: config.fetchTimeoutMs
 		});
-		const ok = out.stdout !== null;
-		fetchState.set(toplevel, { lastAttemptAt: Date.now(), inFlight: null });
-		return ok;
-	})();
-	if (state === void 0) fetchState.set(toplevel, { lastAttemptAt: now, inFlight });
-	else state.inFlight = inFlight;
-	return inFlight;
+		return out.stdout !== null;
+	});
 }
 //#endregion
 
@@ -405,26 +459,19 @@ function prListKey(byBranch) {
  */
 function prStatusFor(toplevel, branch, notify) {
 	if (config.prStatus === "off") return void 0;
-	const now = Date.now();
 	const key = toplevel + "\u0000" + branch;
-	const state = prState.get(key);
-	if (state !== void 0) {
-		// Fresh, or a refresh is already running: serve what we have either way.
-		if (now - state.lastAttemptAt < config.prTtlMs || state.inFlight !== null) return state.value;
-	}
-	const record = { lastAttemptAt: now, inFlight: null, value: state?.value };
-	const inFlight = (async () => {
+	return singleFlight(prState, key, {
+		ttlMs: config.prTtlMs,
+		keepValue: true,
+		// the previous answer is served while a refresh runs, so a forge round
+		// trip is never route latency
+		serve: (state) => state.value
+	}, async (record) => {
 		const value = await readPrStatus(toplevel, branch).catch(() => void 0);
 		const changed = JSON.stringify(record.value ?? null) !== JSON.stringify(value ?? null);
-		record.lastAttemptAt = Date.now();
-		record.inFlight = null;
-		record.value = value;
 		if (changed) notify(toplevel);
 		return value;
-	})();
-	record.inFlight = inFlight;
-	prState.set(key, record);
-	return record.value;
+	});
 }
 //#endregion
 
@@ -586,13 +633,7 @@ const worktreeInFlight = new Map();
  * local git calls, and a worktree created a moment ago must be visible at once.
  */
 function worktreesFor(dir) {
-	const pending = worktreeInFlight.get(dir);
-	if (pending !== void 0) return pending;
-	const run = readWorktrees(dir).finally(() => {
-		worktreeInFlight.delete(dir);
-	});
-	worktreeInFlight.set(dir, run);
-	return run;
+	return singleFlight(worktreeInFlight, dir, {}, () => readWorktrees(dir));
 }
 
 /**
@@ -692,17 +733,24 @@ function legacyOrderFile() {
 }
 
 /**
- * The live order — one in-memory value, updated by the settings scope. It is
- * authoritative only once the namespace actually registered; until then (and on
- * a host without the settings stack, or in a unit test that never calls apply)
- * the legacy file is read per call, which is the pre-settings behaviour.
+ * The live order — one in-memory value. apply() seeds it from the pre-settings
+ * JSON file once at boot; the settings scope then owns it, so a change applies
+ * to the next status read with no file poll and no restart. A host without the
+ * settings stack (and a unit test that never calls apply) simply keeps the
+ * default. Reading the file once per boot instead of per status read keeps a
+ * sync disk read off the hot path; the file's contract is a boot-time seed,
+ * which is all it ever was once the namespace exists.
  */
 let currentOrder = DEFAULT_NEXT_ORDER;
-let settingsOrderActive = false;
+
+/** Seed the live order from the pre-settings JSON file — apply()'s boot step. */
+function seedOrder() {
+	currentOrder = legacyOrderFile();
+}
 
 /** The ranking order every status read uses. */
 function nextOrder() {
-	return settingsOrderActive ? currentOrder : legacyOrderFile();
+	return currentOrder;
 }
 
 /**
@@ -730,7 +778,7 @@ function nextOrder() {
  *
  * @returns {{ args: string, command: string|undefined, why: string, what: string } | null}
  */
-function nextStep(info) {
+function nextStepRules(info) {
 	if (info === void 0 || info === null || info.git !== true) return null;
 	const unmerged = info.unmergedFiles || 0;
 	const plural = (n) => (n === 1 ? "" : "s");
@@ -786,15 +834,71 @@ function nextStep(info) {
 	if (pr !== void 0 && pr.number !== void 0 && pr.state === "failing") {
 		add("checks", `checks ${pr.number}`, `checks failing on #${pr.number}`, "watch the CI checks on pull request " + pr.number, `gh pr checks ${pr.number} --watch`);
 	}
-	if (rules.length === 0) return null;
+
+	// STANDING options: never ranked, never the primary suggestion — they are
+	// things you may do, not things the checkout is asking for. `pr view` exists
+	// whenever a pull request does; `pr` (create) only for a pushed branch that
+	// is not the default; `clean` last and flagged, because a destructive verb
+	// whose intent git status cannot reveal must never be suggested.
+	const standing = [];
+	if (pr !== void 0 && pr.number !== void 0) {
+		standing.push({
+			args: `pr view ${pr.number}`,
+			why: `open pull request #${pr.number}`,
+			what: `show pull request ${pr.number} on GitHub`
+		});
+	} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && dirty === 0 && info.defaultBranch !== true) {
+		standing.push({ args: "pr", why: "branch is pushed and has no pull request", what: "open a pull request for this branch" });
+	}
+	if (untracked > 0) {
+		standing.push({
+			args: "clean",
+			why: `${untracked} untracked file${plural(untracked)}`,
+			what: "remove untracked files — lists them and asks first",
+			danger: true
+		});
+	}
 
 	const order = nextOrder();
 	const rank = (cat) => {
 		const at = order.indexOf(cat);
 		return at === -1 ? order.length : at;
 	};
-	const [top] = [...rules].sort((a, b) => rank(a.cat) - rank(b.cat));
-	return { args: top.args, command: top.command, why: top.why, what: top.what };
+	const ranked = [...rules].sort((a, b) => rank(a.cat) - rank(b.cat)).slice(0, 5);
+	return { ranked, standing };
+}
+
+/**
+ * Every action the checkout justifies, in order — the ONE list both surfaces
+ * render: the card shows the primary entry, the (+) picker lists them all.
+ *
+ * The server owns the whole list because both halves previously carried their
+ * own copy of these conditions and drifted: the card promoted a client-only
+ * extra into its action row, and `/gh pr` was offered on the default branch.
+ * One authority, one list, no reconciliation.
+ *
+ * Exactly one entry can be `primary` (the top RANKED rule) or none at all —
+ * a clean, synced checkout has actions (look at the PR, clean up) but no
+ * suggestion, because "no suggestion" is also a suggestion.
+ *
+ * @returns {{ actions: Array<{args, why, what, command?, danger?, primary?}>, next: object|null }}
+ */
+function nextActions(info) {
+	const built = nextStepRules(info);
+	if (built === null) return { actions: [], next: null };
+	const { ranked, standing } = built;
+	const actions = [
+		...ranked.map((rule, index) => ({
+			args: rule.args,
+			why: rule.why,
+			what: rule.what,
+			...(rule.command === void 0 ? {} : { command: rule.command }),
+			...(index === 0 ? { primary: true } : {})
+		})),
+		...standing
+	];
+	const primary = actions.find((action) => action.primary === true) ?? null;
+	return { actions, next: primary };
 }
 
 /**
@@ -897,6 +1001,15 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		ahead: parsed.ahead,
 		behind: parsed.behind
 	};
+	// Is this the repository's DEFAULT branch? main/master with no pull request
+	// is that branch's normal state, and "open a pull request for this branch" is
+	// nonsense there, so the surfaces suppress it. Cached and refreshed out of
+	// band: the flag may be absent on the very first read, present on the next.
+	const defaultBranch = defaultBranchFor(toplevel, notifyChange);
+	if (defaultBranch !== void 0 && defaultBranch === parsed.branch) info.defaultBranch = true;
+	// Resolved inside the detail block; the PR-token hover below reuses it, so it
+	// is declared here rather than scoped to that block.
+	let baseRef = null;
 	if (wantDetail) {
 		// The ✎n NAMES — the one part of the count the numbers cannot answer
 		// ("what are these?"). Hover-gated with the rest of detail=1, so no
@@ -931,10 +1044,11 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		// `remote get-url origin` with ssh syntax converted; absent when there is
 		// no origin or the URL is not recognisably a hosted repo.
 		// These reads are independent — one batch, so hover latency is the
-		// longest call rather than their sum. The only dependent call (the
-		// left-right count needs a probed base ref) runs after the batch and
-		// tolerates its own failure.
-		const [remoteUrl, probeMain, probeMaster, logOut2, stashOut] = await Promise.all([
+		// longest call rather than their sum. `logHead` is the plain HEAD log
+		// the no-base-branch fallback below serves as the branch's commit list;
+		// the only dependent calls (the left-right count and the signed log both
+		// need a probed base ref) run after the batch and tolerate failure.
+		const [remoteUrl, probeMain, probeMaster, logHead, stashOut] = await Promise.all([
 			runGit(toplevel, ["remote", "get-url", "origin"]),
 			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/main"]),
 			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/master"]),
@@ -944,7 +1058,7 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		if (remoteUrl.stdout !== null && remoteUrl.stdout.trim() !== "") {
 			info.repoUrl = remoteToWebUrl(remoteUrl.stdout);
 		}
-		const baseRef = probeMain.stdout !== null && probeMain.stdout.trim() !== ""
+		baseRef = probeMain.stdout !== null && probeMain.stdout.trim() !== ""
 			? "origin/main"
 			: probeMaster.stdout !== null && probeMaster.stdout.trim() !== "" ? "origin/master" : null;
 		if (baseRef !== null && info.repoUrl !== void 0) {
@@ -987,9 +1101,9 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 				if (Number.isFinite(total)) info.branchCommitsTotal = total;
 			}
 		} else {
-			const plainOut = await runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", "HEAD"]);
-			if (plainOut.stdout !== null && plainOut.stdout.trim() !== "") {
-				info.branchCommits = plainOut.stdout.trim().split("\n").map((line) => {
+			// already fetched in the batch above — no second invocation
+			if (logHead.stdout !== null && logHead.stdout.trim() !== "") {
+				info.branchCommits = logHead.stdout.trim().split("\n").map((line) => {
 					const [hash, subject, when] = line.split("\t");
 					return { hash, subject: subject ?? "", when: when ?? "" };
 				}).filter((c) => c.hash !== void 0);
@@ -1009,45 +1123,46 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
 		if (pr !== void 0) info.pr = pr;
 	}
-	const next = nextStep(info);
+	if (baseRef !== null && info.pr !== void 0 && info.pr !== null && info.pr.number !== void 0
+		&& info.pr.open !== false && (info.mainAhead || 0) > 0) {
+		// The PR's OWN commits (base..HEAD) — the token's hover answers "what is in
+		// this pull request", so it lists exactly that: not the branch's recent
+		// history, nothing else. Hover-gated with the rest of detail=1, and the
+		// total is the ahead count already computed above (no second rev-list).
+		const prOut = await runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", baseRef + "..HEAD"]);
+		if (prOut.stdout !== null && prOut.stdout.trim() !== "") {
+			info.prCommits = prOut.stdout.trim().split("\n").map((line) => {
+				const [hash, subject, when] = line.split("\t");
+				return { hash, subject: subject ?? "", when: when ?? "" };
+			}).filter((c) => c.hash !== void 0);
+			info.prCommitsTotal = info.mainAhead;
+		}
+	}
+	// The ranked suggestion rides EVERY response (it is pure derivation, and a
+	// sidebar row may one day use it instead of its own copy of these rules);
+	// the full action list is sent only for `pr=1`, the surfaces that have a
+	// picker, so a row's payload stays lean.
+	const { actions, next } = nextActions(info);
 	if (next !== null) info.next = next;
+	if (wantPr && actions.length > 0) info.actions = actions;
 	return info;
 }
 
 /** In-flight status reads, so N callers asking at once share one `git status`. */
 const statusInFlight = new Map();
-/** Completed reads inside `config.statusCacheMs`; unused at the 0 default. */
-const statusCache = new Map();
 
 /**
  * Status for dir, with identical CONCURRENT reads collapsed into one. That is the
  * shape a burst of sidebar session rows produces when they mount together: N rows
  * of one workspace resolve to the same directory, and without this they would run
- * N `git status` walks of the same tree at the same instant.
- *
- * The optional `statusCacheMs` window extends the collapse to serial bursts. It
- * defaults to 0 on purpose: a cache that outlives the call would let a caller
- * that mutates a repository and asks again read a stale answer, and correctness
- * of a *status* badge outranks saving a walk.
+ * N `git status` walks of the same tree at the same instant. Deliberately NO
+ * completed-read cache: one that outlived the call would let a caller that
+ * mutates a repository and asks again read a stale answer, and correctness of a
+ * *status* badge outranks saving a walk.
  */
 function gitStatus(dir, wantDetail, wantPr) {
 	const key = dir + "\u0000" + (wantDetail === true) + "\u0000" + (wantPr === true);
-	if (config.statusCacheMs > 0) {
-		const hit = statusCache.get(key);
-		if (hit !== void 0 && Date.now() - hit.at < config.statusCacheMs) return Promise.resolve(hit.value);
-	}
-	const pending = statusInFlight.get(key);
-	if (pending !== void 0) return pending;
-	const run = gitStatusUncached(dir, wantDetail, wantPr)
-		.then((value) => {
-			if (config.statusCacheMs > 0) statusCache.set(key, { at: Date.now(), value });
-			return value;
-		})
-		.finally(() => {
-			statusInFlight.delete(key);
-		});
-	statusInFlight.set(key, run);
-	return run;
+	return singleFlight(statusInFlight, key, {}, () => gitStatusUncached(dir, wantDetail, wantPr));
 }
 
 //#region git-state watcher
@@ -1416,17 +1531,10 @@ async function resolveWorkspace(ctx, params) {
  * directory that is not a worktree of this repository.
  */
 function sessionCheckouts() {
-	if (typeof config.sessionCheckoutsFile === "string") {
-		try {
-			const raw = JSON.parse(readFileSync(config.sessionCheckoutsFile, "utf8"));
-			return raw !== null && typeof raw === "object" && typeof raw.sessions === "object" && raw.sessions !== null
-				? raw.sessions
-				: {};
-		} catch {
-			return {};
-		}
-	}
-	return readSessionCheckouts();
+	// The store owns the file's shape; the test seam only redirects the path.
+	return config.sessionCheckoutsFile === null
+		? readSessionCheckouts()
+		: readSessionCheckouts(config.sessionCheckoutsFile);
 }
 
 async function registeredCheckout(target, sessionId) {
@@ -1485,7 +1593,7 @@ function apply(ctx) {
 	// exists, seeds the namespace as its composition BASE so an order configured
 	// before this existed survives the upgrade; it is also the fallback when the
 	// settings service is absent (a host composed without dsh-settings).
-	currentOrder = legacyOrderFile();
+	seedOrder();
 	if (typeof ctx.inject === "function") {
 		try {
 			ctx.inject(["settings"], async (settingsCtx) => {
@@ -1500,12 +1608,12 @@ function apply(ctx) {
 					base: { order: legacyOrderFile() }
 				});
 				currentOrder = normalizeOrder(scope.get()?.order);
-				settingsOrderActive = true;
 				settingsCtx.effect(() => scope.watch((next) => {
 					currentOrder = normalizeOrder(next?.order);
 				}), "dsh-git-badge: order settings");
 				settingsCtx.effect(() => () => {
-					settingsOrderActive = false;
+					// the namespace is gone: fall back to the boot-time seed
+					seedOrder();
 				}, "dsh-git-badge: order settings teardown");
 			});
 		} catch (error) {
@@ -1648,7 +1756,8 @@ export {
 	config,
 	OPERATION_MARKERS,
 	operationMarker,
-	nextStep,
+	nextActions,
+	seedOrder,
 	outerGitDir,
 	parseStatusV2,
 	parseWorktreeList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Git status badges for DeepSeek Harness: an input-row chip on every install, plus sidebar session-row badges (git status, PR/CI action tokens) after one manual step: `npx dsh-git-badge apply`, then restart dsh web. Event-driven freshness over SSE.",
   "type": "module",
   "main": "lib/index.js",
@@ -22,9 +22,6 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ],
       "platform": "web"
     }
   },
@@ -58,6 +55,7 @@
     "seam/anchors.js",
     "seam/apply.js",
     "seam/checkout.js",
+    "seam/patch.js",
     "seam/postinstall.js",
     "seam/skill.js",
     "seam/store.js",