magus-cli 7.11.6 → 7.11.8

package/src/services/catalog-cache-store.ts

@@ -37,10 +37,11 @@ import type { MarketplacePlugin } from "./marketplace-catalog.js";
  *
  * This is the ONLY refresh rhythm magus has, and it applies to both surfaces:
  * `magus update` and the TUI read a catalog written here within the hour
- * before they go to the network. `update` pulls the marketplace clones and
- * drops its in-process memo before planning, but it does NOT clear this file,
- * so a release published inside the TTL is not seen by `update` either. Only
- * an explicit refresh (`r` in the TUI) clears it. Anything that reports "no
+ * before they go to the network. `update` pulls the marketplace clones (each
+ * at most once per TTL, machine-wide — see `cloneRefreshes`) and drops its
+ * in-process memo before planning, but it does NOT clear this file, so a
+ * release published inside the TTL is not seen by `update` either. Only an
+ * explicit refresh (`r` in the TUI) clears it, clone refresh times included. Anything that reports "no
  * update" — or decides a plugin is no longer published — off a cached catalog
  * is working from an answer up to an hour old, by design.
  */
@@ -93,14 +94,24 @@ interface StoreShape {
 	catalogs: Record<string, StoredCatalog>;
 	cooldowns: Record<string, StoredCooldown>;
 	communityStyles: Record<string, StoredCommunityCheck>;
+	/**
+	 * Per marketplace: wall-clock ms of the last SUCCESSFUL fast-forward of its
+	 * on-disk clone. Machine-wide, so one project's `magus update` spares every
+	 * other project's the same pull within CATALOG_TTL_MS.
+	 */
+	cloneRefreshes: Record<string, number>;
 }
 
-const EMPTY: StoreShape = {
-	version: 1,
-	catalogs: {},
-	cooldowns: {},
-	communityStyles: {},
-};
+/** A fresh empty store. A function, so no caller can share and mutate one object. */
+function emptyStore(): StoreShape {
+	return {
+		version: 1,
+		catalogs: {},
+		cooldowns: {},
+		communityStyles: {},
+		cloneRefreshes: {},
+	};
+}
 
 /**
  * Resolved per call, honouring CLAUDE_CONFIG_DIR — same reasoning as
@@ -124,29 +135,24 @@ let memo: { path: string; data: StoreShape } | null = null;
 
 async function load(): Promise<StoreShape> {
 	const file = storePath();
-	if (!file)
-		return { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+	if (!file) return emptyStore();
 	if (memo?.path === file) return memo.data;
 	try {
 		const parsed = JSON.parse(await fs.readFile(file, "utf-8")) as StoreShape;
 		// A cache from a future/unknown layout is discarded rather than migrated:
 		// it is regenerable by definition, so guessing at it buys nothing.
-		const data = parsed?.version === 1 ? parsed : { ...EMPTY };
+		const data = parsed?.version === 1 ? parsed : emptyStore();
 		data.catalogs ??= {};
 		data.cooldowns ??= {};
-		// Absent in every file written before community styles existed, so this
+		// Absent in every file written before these sections existed, so the
 		// default is the migration — an upgrade must not read as a corrupt cache.
 		data.communityStyles ??= {};
+		data.cloneRefreshes ??= {};
 		memo = { path: file, data };
 		return data;
 	} catch {
 		// Absent or corrupt. A cache must never be a failure mode — start empty.
-		const data: StoreShape = {
-			...EMPTY,
-			catalogs: {},
-			cooldowns: {},
-			communityStyles: {},
-		};
+		const data = emptyStore();
 		memo = { path: file, data };
 		return data;
 	}
@@ -179,15 +185,11 @@ async function mutate(fn: (data: StoreShape) => void): Promise<void> {
 								catalogs: parsed.catalogs ?? {},
 								cooldowns: parsed.cooldowns ?? {},
 								communityStyles: parsed.communityStyles ?? {},
+								cloneRefreshes: parsed.cloneRefreshes ?? {},
 							}
-						: { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+						: emptyStore();
 			} catch {
-				onDisk = {
-					version: 1,
-					catalogs: {},
-					cooldowns: {},
-					communityStyles: {},
-				};
+				onDisk = emptyStore();
 			}
 			fn(onDisk);
 			// Temp + rename, so a crash mid-write cannot leave a half-written file
@@ -312,6 +314,44 @@ export async function clearCommunityChecks(): Promise<void> {
 	});
 }
 
+// ─── Marketplace clone refreshes ─────────────────────────────────────────────
+
+/**
+ * Milliseconds since this marketplace's clone was last fast-forwarded
+ * successfully, or null when that was never, longer ago than CATALOG_TTL_MS, or
+ * in the future (a clock that moved back must not freeze the clone).
+ *
+ * Same TTL as the catalogs, on purpose: the clone and the catalog answer the
+ * same question, so they go stale on one rhythm and `r` clears both.
+ */
+export async function readCloneRefreshAge(
+	marketplace: string,
+	now: number = Date.now(),
+): Promise<number | null> {
+	const at = (await load()).cloneRefreshes[marketplace];
+	if (typeof at !== "number") return null;
+	const ageMs = now - at;
+	if (ageMs < 0 || ageMs > CATALOG_TTL_MS) return null;
+	return ageMs;
+}
+
+/** Record a successful fast-forward. Never called for a failed or skipped pull. */
+export async function writeCloneRefreshed(
+	marketplace: string,
+	now: number = Date.now(),
+): Promise<void> {
+	await mutate((data) => {
+		data.cloneRefreshes[marketplace] = now;
+	});
+}
+
+/** Drop every clone refresh time. Backs the explicit refresh (`r`). */
+export async function clearCloneRefreshes(): Promise<void> {
+	await mutate((data) => {
+		data.cloneRefreshes = {};
+	});
+}
+
 /** Test seam: forget this process's memo so the next read hits disk. */
 export function resetCatalogCacheMemo(): void {
 	memo = null;

package/src/services/marketplace-catalog-git.ts

@@ -27,10 +27,10 @@
  * working precisely when the HTTP catalog cannot.
  */
 
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { claudeConfigDirOrNull } from "../utils/config-dir.js";
+import { runBounded } from "../utils/spawn-bounded.js";
 import {
 	type MarketplacePlugin,
 	normalizeCatalogJson,
@@ -55,36 +55,27 @@ function cloneDir(name: string): string | null {
 	return path.join(configDir, "plugins", "marketplaces", name);
 }
 
-function git(
+async function git(
 	cwd: string,
 	args: string[],
 	timeoutMs: number,
 ): Promise<{ ok: boolean; out: string }> {
-	return new Promise((resolve) => {
-		const child = spawn("git", args, {
-			cwd,
-			stdio: ["ignore", "pipe", "ignore"],
-			timeout: timeoutMs,
-			killSignal: "SIGKILL",
-			env: {
-				...process.env,
-				// Never let git stop for credentials: this runs inside a TUI with no
-				// way to answer a prompt, and a private marketplace we cannot read
-				// should degrade to "unknown", not hang the screen forever.
-				GIT_TERMINAL_PROMPT: "0",
-				GIT_ASKPASS: "echo",
-				SSH_ASKPASS: "echo",
-			},
-		});
-		let out = "";
-		child.stdout.on("data", (d: Buffer | string) => {
-			out += String(d);
-		});
-		child.on("error", () => resolve({ ok: false, out: "" }));
-		child.on("close", (code: number | null) =>
-			resolve({ ok: code === 0, out }),
-		);
+	const r = await runBounded("git", args, {
+		cwd,
+		stdio: ["ignore", "pipe", "ignore"],
+		timeoutMs,
+		env: {
+			...process.env,
+			// Never let git stop for credentials: this runs inside a TUI with no
+			// way to answer a prompt, and a private marketplace we cannot read
+			// should degrade to "unknown", not hang the screen forever.
+			GIT_TERMINAL_PROMPT: "0",
+			GIT_ASKPASS: "echo",
+			SSH_ASKPASS: "echo",
+		},
 	});
+	if (r.spawnError) return { ok: false, out: "" };
+	return { ok: r.code === 0, out: r.stdout };
 }
 
 /**

package/src/services/marketplace-fetcher.ts

@@ -10,6 +10,7 @@
 import { isValidGitHubRepo } from "../utils/string-utils.js";
 import {
 	clearCachedCatalogs,
+	clearCloneRefreshes,
 	readCachedCatalog,
 	writeCachedCatalog,
 } from "./catalog-cache-store.js";
@@ -145,6 +146,9 @@ export function clearMarketplaceCache(): void {
  */
 export async function clearPersistedCatalogs(): Promise<void> {
 	await clearCachedCatalogs();
+	// The clone refresh times too: an explicit refresh means "ask again now", so
+	// the next `magus update` pulls every needed clone instead of trusting the hour.
+	await clearCloneRefreshes();
 }
 
 /**

package/src/services/marketplace-refresh.ts

@@ -17,71 +17,114 @@
  * A failed `git pull --ff-only` leaves the clone exactly as it was: stale, but intact.
  */
 
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { runBounded } from "../utils/spawn-bounded.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import {
+	readCloneRefreshAge,
+	writeCloneRefreshed,
+} from "./catalog-cache-store.js";
 import {
 	getConfiguredMarketplaces,
 	getGlobalClaudeDir,
+	getGlobalEnabledPlugins,
 	getMarketplaceAutoUpdate,
 } from "./claude-settings.js";
 
 /** Per-git-invocation timeout. A hung pull must never block launching Claude. */
 const GIT_TIMEOUT_MS = 30_000;
 
+/** Hard cap per clone, whatever hangs: `git status` then `git pull`, each GIT_TIMEOUT_MS, plus slack. */
+const CLONE_DEADLINE_MS = 2 * GIT_TIMEOUT_MS + 5_000;
+
 export interface RefreshResult {
 	/** Clones fast-forwarded to a newer commit (or already current). */
 	refreshed: string[];
 	/** Pull errored (network, diverged, timeout) — clone left intact and stale. */
 	failed: string[];
-	/** Nothing to do: no clone on disk, not a git repo, or dirty tree. */
+	/**
+	 * Not pulled because this machine already refreshed the clone successfully
+	 * within CATALOG_TTL_MS — by this project's run or any other.
+	 */
+	fresh: string[];
+	/**
+	 * Report-only: selected, and a writing run would pull it. Always empty when
+	 * the refresh actually ran.
+	 */
+	pending: string[];
+	/**
+	 * Not pulled, and not a failure: no installed plugin comes from it, not a
+	 * github source, autoUpdate off, no clone on disk, or dirty tree.
+	 */
 	skipped: string[];
 }
 
+export interface RefreshOptions {
+	/**
+	 * Plugin ids (`name@marketplace`) this run installs — the profile's
+	 * PROJECT/LOCAL set. Unioned with every plugin installed at USER scope;
+	 * a marketplace none of them comes from is not pulled.
+	 */
+	pluginIds?: Iterable<string>;
+	/** Clock seam for the once-an-hour rule. */
+	now?: number;
+}
+
+/**
+ * The marketplaces some installed plugin comes from: the ones passed in
+ * (PROJECT/LOCAL, from the profile) plus every plugin turned on at USER scope.
+ * A USER entry set to `false` is not installed and does not count.
+ */
+async function neededMarketplaces(
+	pluginIds: Iterable<string>,
+): Promise<Set<string>> {
+	const ids = [...pluginIds];
+	for (const [id, on] of Object.entries(await getGlobalEnabledPlugins())) {
+		if (on === true) ids.push(id);
+	}
+	const needed = new Set<string>();
+	for (const id of ids) {
+		const parsed = parsePluginId(id);
+		if (parsed) needed.add(parsed.marketplace);
+	}
+	return needed;
+}
+
 function cloneDir(name: string): string {
 	return path.join(getGlobalClaudeDir(), "plugins", "marketplaces", name);
 }
 
-/** Run git in `cwd`, resolving stdout on exit 0. Killed after `timeoutMs`. */
-function runGit(
+/**
+ * Run git in `cwd`, resolving stdout on exit 0. Killed after `timeoutMs`, or as
+ * soon as `signal` aborts (an already-aborted signal runs nothing). Throws on
+ * anything but exit 0.
+ */
+async function runGit(
 	cwd: string,
 	args: string[],
 	timeoutMs: number,
+	signal?: AbortSignal,
 ): Promise<string> {
-	return new Promise((resolve, reject) => {
-		const proc = spawn("git", args, {
-			cwd,
-			timeout: timeoutMs,
-			killSignal: "SIGKILL",
-		});
-		let stdout = "";
-		let stderr = "";
-		proc.stdout?.on("data", (b) => {
-			stdout += b.toString();
-		});
-		proc.stderr?.on("data", (b) => {
-			stderr += b.toString();
-		});
-		proc.on("error", reject);
-		proc.on("close", (code, signal) => {
-			if (code === 0) {
-				resolve(stdout);
-			} else {
-				reject(
-					new Error(
-						`git ${args.join(" ")} ${
-							signal ? `killed (${signal})` : `exited ${code}`
-						}: ${stderr.trim()}`,
-					),
-				);
-			}
-		});
-	});
+	const r = await runBounded("git", args, { cwd, timeoutMs, signal });
+	if (r.spawnError) throw r.spawnError;
+	if (r.code === 0 && !r.aborted) return r.stdout;
+	const how = r.aborted
+		? "aborted"
+		: r.signal
+			? `killed (${r.signal})`
+			: `exited ${r.code}`;
+	throw new Error(`git ${args.join(" ")} ${how}: ${r.stderr.trim()}`);
 }
 
 /** True if the clone has uncommitted changes we must not clobber. */
-async function isDirty(dir: string): Promise<boolean> {
-	const out = await runGit(dir, ["status", "--porcelain"], GIT_TIMEOUT_MS);
+async function isDirty(dir: string, signal?: AbortSignal): Promise<boolean> {
+	const out = await runGit(
+		dir,
+		["status", "--porcelain"],
+		GIT_TIMEOUT_MS,
+		signal,
+	);
 	return out.trim().length > 0;
 }
 
@@ -99,23 +142,50 @@ export type CloneRefresh = "absent" | "skipped" | "refreshed" | "failed";
  * deletes: the worst case is `failed` (stale clone left intact). Shared by the
  * batch refresh below and by claude-cli's "plugin not found" recovery, so both
  * paths get the same safe semantics instead of the old `marketplace update`.
+ *
+ * Bounded by `deadlineMs`: when it passes, the result is `failed` and the git
+ * command then in flight (`status` or `pull`) is SIGKILLed; no further git
+ * command starts. Only that direct child is killed: a `git fetch` or `ssh` it
+ * spawned may linger until it exits on its own, holding nothing we wait on.
+ * The clone directory is never deleted, but a pull killed while it updates the
+ * working tree can leave that update part-way and a `.git/index.lock` behind;
+ * later pulls then return `failed` until the lock is removed. The deadline sits
+ * well above a healthy pull, so that is the price of never hanging, not a
+ * normal outcome.
  */
 export async function fastForwardCloneIfPresent(
 	name: string,
+	deadlineMs: number = CLONE_DEADLINE_MS,
 ): Promise<CloneRefresh> {
 	const dir = cloneDir(name);
 	// No clone on disk (claude never installed it) or not a git repo.
 	if (!fs.existsSync(path.join(dir, ".git"))) return "absent";
+	const abort = new AbortController();
+	const work = (async (): Promise<CloneRefresh> => {
+		try {
+			// Never clobber a user's local edits to the clone.
+			if (await isDirty(dir, abort.signal)) return "skipped";
+			// --ff-only is the safety guarantee: it fetches and fast-forwards, and
+			// aborts without mutating the tree if it can't. It never deletes the dir,
+			// so a failure degrades to "stale clone", never "deleted marketplace".
+			await runGit(dir, ["pull", "--ff-only"], GIT_TIMEOUT_MS, abort.signal);
+			return "refreshed";
+		} catch {
+			return "failed";
+		}
+	})();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<CloneRefresh>((resolve) => {
+		timer = setTimeout(() => {
+			// Kill the in-flight git child rather than leave it running.
+			abort.abort();
+			resolve("failed");
+		}, deadlineMs);
+	});
 	try {
-		// Never clobber a user's local edits to the clone.
-		if (await isDirty(dir)) return "skipped";
-		// --ff-only is the safety guarantee: it fetches and fast-forwards, and
-		// aborts without mutating the tree if it can't. It never deletes the dir,
-		// so a failure degrades to "stale clone", never "deleted marketplace".
-		await runGit(dir, ["pull", "--ff-only"], GIT_TIMEOUT_MS);
-		return "refreshed";
-	} catch {
-		return "failed";
+		return await Promise.race([work, deadline]);
+	} finally {
+		clearTimeout(timer);
 	}
 }
 
@@ -150,46 +220,62 @@ function tap(fn: (() => void) | undefined): void {
 	}
 }
 
-/**
- * Non-destructively fast-forward the on-disk clone of every registered,
- * auto-update-enabled, github-sourced marketplace.
- *
- * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
- *   so they aren't pulled twice.
- * @param progress optional taps for a live progress display.
- * @returns which marketplaces were refreshed, which failed (clone left intact),
- *   and which were skipped. Failures and skips are collected rather than thrown —
- *   one unreachable marketplace must not block launching Claude. Pulls run
- *   concurrently, so a slow one doesn't serialize the rest onto the launch path.
- */
 /**
  * Select and report, writing nothing.
  *
- * Everything above the pull loop is a read — the marketplace registry and each
- * entry's `autoUpdate` flag — so a read-only caller can have the full selection
- * verdict for free. `--dry-run` and `--check` promise to write nothing and
- * therefore cannot pull, but they must still be able to say "your magus clone
- * has autoUpdate off, so its catalog will never advance". Gating the whole call
- * off silently dropped that warning, which is the same "no signal reads as no
- * problem" failure the flag exists to prevent.
+ * Everything above the pull loop is a read — the marketplace registry, each
+ * entry's `autoUpdate` flag, which marketplaces installed plugins come from,
+ * and when each clone was last refreshed — so a read-only caller can have the
+ * full selection verdict for free. `--dry-run` and `--check` promise to write
+ * nothing and therefore cannot pull (nor record a refresh time), but their
+ * report must name the same set a writing run would pull: that set is
+ * `pending`.
  */
 export async function reportRegisteredMarketplaces(
 	skip: Iterable<string> = [],
+	options: RefreshOptions = {},
 ): Promise<RefreshResult> {
-	return refreshRegisteredMarketplaces(skip, {}, { reportOnly: true });
+	return selectAndRefresh(skip, {}, { ...options, reportOnly: true });
 }
 
+/**
+ * Non-destructively fast-forward the on-disk clone of every registered,
+ * auto-update-enabled, github-sourced marketplace that some installed plugin
+ * comes from (USER scope, or `options.pluginIds`), unless this machine already
+ * refreshed it within CATALOG_TTL_MS. A successful pull records its time; a
+ * failed one does not, so the next run retries.
+ *
+ * @param skip marketplaces already refreshed this run (e.g. re-registered ones),
+ *   so they aren't pulled twice.
+ * @param progress optional taps for a live progress display.
+ * @returns which marketplaces were refreshed, which failed (clone left intact),
+ *   which were fresh, and which were skipped. Failures and skips are collected
+ *   rather than thrown — one unreachable marketplace must not block launching
+ *   Claude. Pulls run concurrently, so a slow one doesn't serialize the rest
+ *   onto the launch path.
+ */
 export async function refreshRegisteredMarketplaces(
 	skip: Iterable<string> = [],
 	progress: RefreshProgress = {},
-	options: { reportOnly?: boolean } = {},
+	options: RefreshOptions = {},
+): Promise<RefreshResult> {
+	return selectAndRefresh(skip, progress, { ...options, reportOnly: false });
+}
+
+async function selectAndRefresh(
+	skip: Iterable<string>,
+	progress: RefreshProgress,
+	options: RefreshOptions & { reportOnly: boolean },
 ): Promise<RefreshResult> {
 	const refreshed: string[] = [];
 	const failed: string[] = [];
+	const fresh: string[] = [];
 	const skipped: string[] = [];
+	const now = options.now ?? Date.now();
 
 	const configured = await getConfiguredMarketplaces();
 	const skipSet = new Set(skip);
+	const needed = await neededMarketplaces(options.pluginIds ?? []);
 
 	// Select eligible marketplaces first so the pulls can run concurrently.
 	const eligible: string[] = [];
@@ -208,18 +294,25 @@ export async function refreshRegisteredMarketplaces(
 			skipped.push(name);
 			continue;
 		}
+		// Nothing installed at any scope comes from it, so a pull buys nothing.
+		if (!needed.has(name)) {
+			skipped.push(name);
+			continue;
+		}
+		// Refreshed on this machine within the hour, by any project's run.
+		if ((await readCloneRefreshAge(name, now)) !== null) {
+			fresh.push(name);
+			continue;
+		}
 		eligible.push(name);
 	}
 
 	// A read-only caller stops here, with the selection verdict intact and not
-	// one clone touched. `eligible` becomes `skipped`: nothing was refreshed, so
-	// claiming otherwise would be the false "all current" this module guards.
+	// one clone touched. `eligible` becomes `pending`, never `refreshed`: nothing
+	// was pulled, so claiming otherwise would be the false "all current" this
+	// module guards.
 	if (options.reportOnly) {
-		return {
-			refreshed: [],
-			failed: [],
-			skipped: [...skipped, ...eligible],
-		};
+		return { refreshed: [], failed: [], fresh, pending: eligible, skipped };
 	}
 
 	// Fast-forward every eligible clone in parallel so a slow one doesn't
@@ -241,5 +334,9 @@ export async function refreshRegisteredMarketplaces(
 		else skipped.push(name); // absent | skipped
 	});
 
-	return { refreshed, failed, skipped };
+	// Only a successful pull earns the hour. A failed, absent or dirty clone
+	// records nothing, so the next run — from any project — tries again.
+	for (const name of refreshed) await writeCloneRefreshed(name, now);
+
+	return { refreshed, failed, fresh, pending: [], skipped };
 }