magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/cli-tool-commands.ts

@@ -0,0 +1,133 @@
+/**
+ * The three commands the CLI-tools screen can run against a catalogue entry:
+ * install, update, uninstall.
+ *
+ * A module rather than helpers inside the screen, for two reasons:
+ *
+ *  - **The duplicate.** Uninstall existed twice — once in `CliToolsScreen.tsx`
+ *    and once in `cliToolRenderers.tsx` (as `getUninstallHint`) — because the
+ *    renderer needs to SHOW it and the screen needs to RUN it. The two copies
+ *    had already drifted: one emitted `pip uninstall`, the other
+ *    `pip uninstall -y`. Both were wrong in the same way, which is the point —
+ *    a bug in a duplicated builder has to be found twice.
+ *  - **Testability.** As `.tsx` helpers these were unreachable from a suite that
+ *    cannot render React. As pure functions over data they are pinned by
+ *    `cli-tool-commands.test.ts`, which is what proves no arm emits a bare
+ *    `pip` — the defect that shipped.
+ *
+ * Import direction stays acyclic: renderer → service, screen → service +
+ * renderer.
+ */
+
+import type { CliTool } from "../data/cli-tools.js";
+import type { Command } from "../utils/command-utils.js";
+import {
+	binInstallCommand,
+	binUninstallCommand,
+	binUpgradeCommand,
+} from "./toolchain.js";
+
+/**
+ * How a tool turned out to be installed, as detected from its path on disk.
+ *
+ * NOT the same question as `CliTool.packageManager`, and deliberately not the
+ * same type. `packageManager` is how magus WOULD install the tool; this is
+ * how it IS installed — which may be neither, since a user can `pnpm add -g` or
+ * `yarn global add` something the catalogue calls an npm package. Updating has
+ * to follow what is actually on the machine, or it installs a second copy
+ * beside the first and the screen then reports a conflict it created itself.
+ *
+ * `pnpm`, `yarn` and `unknown` have no `BinInstaller` counterpart, which is why
+ * the two unions stay separate rather than one being widened into the other.
+ */
+export type InstallMethod =
+	| "npm"
+	| "bun"
+	| "pnpm"
+	| "yarn"
+	| "brew"
+	| "pip"
+	| "unknown";
+
+/**
+ * Install a catalogue tool, derived from the entry's own fields.
+ *
+ * Entries used to carry a literal `installCommand` string beside the
+ * `packageManager` and `packageName` that describe the same thing, so the two
+ * could disagree — and did. `aider` declared `packageName: "aider-chat"` and
+ * `checkCommand: "aider --version"`, and its `installCommand` installed
+ * `aider-install`: a bootstrapper whose version nothing in this screen ever
+ * looked at, while the version check queried `aider-chat`. Deriving makes that
+ * disagreement unrepresentable rather than merely fixed.
+ */
+export function cliToolInstall(tool: CliTool): Command {
+	return binInstallCommand({
+		name: tool.name,
+		via: tool.packageManager,
+		package: tool.packageName,
+	});
+}
+
+/**
+ * Update a tool, following the method it was ACTUALLY installed with.
+ *
+ * Returns null when there is nothing sound to run — an `unknown` method means
+ * the detector could not attribute the binary on PATH to any package manager,
+ * and guessing there would install a second copy alongside the one already
+ * there. Callers fall back to installing.
+ */
+export function cliToolUpdate(
+	tool: CliTool,
+	method: InstallMethod,
+	brewFormula?: string,
+): Command | null {
+	switch (method) {
+		// The three the resolver does not model. `pnpm`/`yarn` are not
+		// BinInstallers because magus never chooses them — it only finds them.
+		case "pnpm":
+			return { cmd: "pnpm", args: ["install", "-g", tool.packageName] };
+		case "yarn":
+			return { cmd: "yarn", args: ["global", "add", tool.packageName] };
+		case "unknown":
+			return null;
+		default:
+			// TS has narrowed to "npm" | "bun" | "brew" | "pip" here, which is
+			// assignable to BinInstaller — so the four real installers delegate,
+			// and `pip` in particular gets the uv/pipx/python3 resolution instead
+			// of the bare `pip` this switch used to fall through to.
+			return binUpgradeCommand({
+				name: tool.name,
+				via: method,
+				package: tool.packageName,
+				formula: brewFormula,
+			});
+	}
+}
+
+/**
+ * Remove a tool, following the method it was actually installed with.
+ *
+ * Null means "no command to offer": `unknown` for the reason above, and `go`
+ * because a `go install` binary has no uninstaller to call.
+ */
+export function cliToolUninstall(
+	tool: CliTool,
+	method: InstallMethod,
+	brewFormula?: string,
+): Command | null {
+	switch (method) {
+		case "pnpm":
+			return { cmd: "pnpm", args: ["remove", "-g", tool.packageName] };
+		case "yarn":
+			return { cmd: "yarn", args: ["global", "remove", tool.packageName] };
+		case "unknown":
+			return null;
+		default:
+			return binUninstallCommand({
+				name: tool.name,
+				via: method,
+				package: tool.packageName,
+				formula: brewFormula,
+			});
+	}
+}

package/src/services/community-fetcher.ts

@@ -0,0 +1,90 @@
+/**
+ * community-fetcher.ts — the one thing in the community-styles feature that
+ * knows `fetch` exists.
+ *
+ * ## Why a port at all
+ *
+ * Exactly one boundary gets an interface: the network. The domain here is thin,
+ * and an interface-per-class reflex would be waste — so there is no Strategy
+ * registry, no adapter factory, and nothing else in the feature is abstracted.
+ * The gain is the one the constraints demand: no test can reach GitHub, because
+ * every exported function in `community-styles.ts` takes a `StyleFetcher` as a
+ * REQUIRED argument. Omitting it is a type error, not a forgotten mock.
+ *
+ * ## Why it does not speak `Response`
+ *
+ * The classic way a port leaks its adapter. A `Response` drags in streaming
+ * semantics, a body that can only be read once, and a `fetch`-shaped mental
+ * model into every test fake. `{ status, body, etag }` is what the caller
+ * actually uses.
+ *
+ * `headers` is the one deliberate exception. `github-budget.ts` parses
+ * `retry-after` / `x-ratelimit-reset` / `x-ratelimit-remaining` itself, and it
+ * is the module that knows the two hosts differ in what they report. Re-deriving
+ * that here would fork the rate-limit logic, which is precisely what §5.3 of the
+ * design forbids. A fake supplies `new Headers({...})`, which is a standard
+ * built-in, not a fetch import.
+ */
+
+/** What the application needs from an HTTP response. Never a `Response`. */
+export interface StyleFetchResponse {
+	status: number;
+	/** Empty for a 304 and for any status with no body. */
+	body: string;
+	etag: string | null;
+	contentType: string | null;
+	/** Handed to `github-budget` unchanged — see the header note. */
+	headers: Headers;
+}
+
+export type StyleFetcher = (
+	url: string,
+	opts?: { etag?: string | null; timeoutMs?: number; accept?: string },
+) => Promise<StyleFetchResponse>;
+
+/**
+ * 10s, matching `marketplace-fetcher.ts`. A style is a few kilobytes over a CDN
+ * — measured at ~340ms — so anything past ten seconds is a broken route rather
+ * than a slow one, and the user is waiting on a keypress they just made.
+ */
+export const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * The real adapter. Wraps global `fetch` and nothing more: no retry, no
+ * classification, no budget check. Those are policy and belong in the service,
+ * where they can be tested without a network.
+ *
+ * Sends `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` to `api.github.com`
+ * ONLY — exactly as `skills-manager.ts` already does. The token raises that
+ * host's 60/hr unauthenticated budget to 5000/hr and is the documented escape
+ * hatch when the advisory says the budget is spent. It is never sent to
+ * `raw.githubusercontent.com`, which needs no auth and would receive a
+ * credential it has no business seeing.
+ */
+export const githubFetcher: StyleFetcher = async (url, opts = {}) => {
+	const headers: Record<string, string> = {
+		accept: opts.accept ?? "text/plain, */*",
+		"user-agent": "magus",
+	};
+	if (opts.etag) headers["if-none-match"] = opts.etag;
+
+	if (new URL(url).hostname === "api.github.com") {
+		const token =
+			process.env.GITHUB_TOKEN || process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+		if (token) headers.authorization = `Bearer ${token}`;
+	}
+
+	const response = await fetch(url, {
+		headers,
+		signal: AbortSignal.timeout(opts.timeoutMs ?? FETCH_TIMEOUT_MS),
+	});
+
+	return {
+		status: response.status,
+		// 304 carries no body; reading it is still safe and yields "".
+		body: response.status === 304 ? "" : await response.text(),
+		etag: response.headers.get("etag"),
+		contentType: response.headers.get("content-type"),
+		headers: response.headers,
+	};
+};