magus-cli 0.0.0-placeholder → 7.0.0

package/scripts/verify-community-registry.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env bun
+/**
+ * verify-community-registry.ts — the gate between a proposed community style
+ * entry and a committed one.
+ *
+ * This is NOT a test. It hits the real network, it is run by a human who is
+ * curating the registry, and it must never run in CI: it would burn the shared
+ * 60/hr `api.github.com` budget on every push and then fail on GitHub's rate
+ * limit rather than on our bug, which is the worst possible signal.
+ *
+ * Two modes:
+ *
+ *   --discover                  list the real `.md` blobs and their upstream
+ *   --discover <repo> <dir>     `name`, for every registry source or for one
+ *                               candidate repo. Prints a paste-ready registry
+ *                               block. NEVER hand-write a path from a README:
+ *                               a wrong path is a 404 the user sees, and the
+ *                               error text blames magus for it, correctly.
+ *
+ *   --check                     re-fetch every committed entry and report 404s,
+ *                               size outliers and unparseable files. Run this
+ *                               before committing a registry change.
+ *
+ * Cost: `--discover` spends ONE api.github.com call per repo (a recursive git
+ * tree), then reads names over raw.githubusercontent.com, which costs nothing.
+ * `--check` spends zero API budget.
+ */
+
+import { parseArgs } from "node:util";
+import {
+	COMMUNITY_SOURCES,
+	COMMUNITY_STYLES,
+	type CommunityStyleSource,
+	coordinateProblem,
+	rawUrlFor,
+} from "../src/data/community-styles.js";
+import { githubFetcher } from "../src/services/community-fetcher.js";
+import { MAX_STYLE_BYTES } from "../src/services/community-styles.js";
+import { splitFrontmatter } from "../src/services/styles-manager.js";
+
+interface DiscoveredFile {
+	path: string;
+	/** Upstream's own `name`, or the basename when the file declares none. */
+	displayName: string;
+	description: string;
+	bytes: number;
+}
+
+/** `attention-span/output-styles/zen-master.md` -> `zen-master`. */
+function slugFromPath(filePath: string): string {
+	return (filePath.split("/").pop() ?? filePath).replace(/\.md$/, "");
+}
+
+async function discover(
+	repo: string,
+	dir: string,
+	ref: string,
+): Promise<DiscoveredFile[]> {
+	// ONE API call for the whole repo. Asking per-directory would cost one call
+	// per level and tell us less.
+	const treeUrl = `https://api.github.com/repos/${repo}/git/trees/${ref}?recursive=1`;
+	const tree = await githubFetcher(treeUrl, {
+		accept: "application/vnd.github+json",
+	});
+	if (tree.status !== 200) {
+		throw new Error(
+			`${repo}: HTTP ${tree.status} listing the git tree${
+				tree.status === 403 || tree.status === 429
+					? " (rate limited — wait, or export GITHUB_TOKEN)"
+					: ""
+			}`,
+		);
+	}
+	const parsed = JSON.parse(tree.body) as {
+		truncated?: boolean;
+		tree?: Array<{ path?: string; type?: string }>;
+	};
+	if (parsed.truncated) {
+		console.warn(
+			`  ! ${repo}: git tree was truncated by GitHub — list is partial`,
+		);
+	}
+
+	const prefix = `${dir}/`;
+	const paths = (parsed.tree ?? [])
+		.filter(
+			(entry) =>
+				entry.type === "blob" &&
+				typeof entry.path === "string" &&
+				entry.path.startsWith(prefix) &&
+				entry.path.endsWith(".md") &&
+				// One directory deep only: the cache is flat and a nested style would
+				// need a slug that is not a plain basename.
+				!entry.path.slice(prefix.length).includes("/"),
+		)
+		.map((entry) => entry.path as string)
+		.sort();
+
+	const files: DiscoveredFile[] = [];
+	for (const filePath of paths) {
+		// raw.githubusercontent.com costs no API budget, so reading every file to
+		// get its real `name` is free. This is the only way to get a displayName
+		// that is upstream's own rather than one we invented from a filename.
+		const raw = await githubFetcher(
+			`https://raw.githubusercontent.com/${repo}/${ref}/${filePath}`,
+		);
+		if (raw.status !== 200) {
+			console.warn(`  ! ${filePath}: HTTP ${raw.status}`);
+			continue;
+		}
+		const { frontmatter } = splitFrontmatter(raw.body);
+		files.push({
+			path: filePath,
+			displayName: frontmatter.name || slugFromPath(filePath),
+			description: frontmatter.description || "",
+			bytes: Buffer.byteLength(raw.body, "utf8"),
+		});
+	}
+	return files;
+}
+
+function printDiscovered(
+	sourceId: string,
+	repo: string,
+	files: DiscoveredFile[],
+): void {
+	console.log(`\n${repo} — ${files.length} style file(s)`);
+	console.log("─".repeat(72));
+	for (const file of files) {
+		const flag = file.bytes > MAX_STYLE_BYTES ? "  ** OVER 64 KiB **" : "";
+		console.log(
+			`  {\n\t\tid: "${sourceId}--${slugFromPath(file.path)}",\n\t\tsourceId: "${sourceId}",\n\t\tpath: "${file.path}",\n\t\tdisplayName: ${JSON.stringify(file.displayName)},\n\t\tsummary: ${JSON.stringify(file.description.slice(0, 100))},\n\t},${flag}`,
+		);
+	}
+}
+
+async function runDiscover(repo?: string, dir?: string): Promise<number> {
+	const targets: Array<{ id: string; repo: string; dir: string; ref: string }> =
+		repo && dir
+			? [{ id: repo.split("/")[1] ?? repo, repo, dir, ref: "HEAD" }]
+			: COMMUNITY_SOURCES.map((source: CommunityStyleSource) => ({
+					id: source.id,
+					repo: source.repo,
+					dir: source.dir,
+					ref: source.ref,
+				}));
+
+	let failures = 0;
+	for (const target of targets) {
+		try {
+			const files = await discover(target.repo, target.dir, target.ref);
+			printDiscovered(target.id, target.repo, files);
+			if (files.length === 0) {
+				// The rule that keeps `caveman` and `humanizer` out: zero style files
+				// means there is nothing to import, whatever the star count says.
+				console.log(
+					"  (no style files — this repo must NOT get a registry entry)",
+				);
+			}
+		} catch (error) {
+			failures++;
+			console.error(
+				`  ! ${target.repo}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+	return failures;
+}
+
+async function runCheck(): Promise<number> {
+	let problems = 0;
+	console.log(
+		`Checking ${COMMUNITY_STYLES.length} entries across ${COMMUNITY_SOURCES.length} sources — zero API budget.\n`,
+	);
+
+	for (const style of COMMUNITY_STYLES) {
+		const source = COMMUNITY_SOURCES.find((s) => s.id === style.sourceId);
+		if (!source) {
+			console.error(
+				`✗ ${style.id}: sourceId "${style.sourceId}" resolves to nothing`,
+			);
+			problems++;
+			continue;
+		}
+		const coordinate = coordinateProblem(style, source);
+		if (coordinate) {
+			console.error(`✗ ${style.id}: ${coordinate}`);
+			problems++;
+			continue;
+		}
+
+		const response = await githubFetcher(rawUrlFor(style, source));
+		if (response.status !== 200) {
+			console.error(
+				`✗ ${style.id}: HTTP ${response.status} — ${rawUrlFor(style, source)}`,
+			);
+			problems++;
+			continue;
+		}
+		const bytes = Buffer.byteLength(response.body, "utf8");
+		if (bytes > MAX_STYLE_BYTES) {
+			console.error(`✗ ${style.id}: ${bytes} bytes exceeds the 64 KiB cap`);
+			problems++;
+			continue;
+		}
+		const { frontmatter, body } = splitFrontmatter(response.body);
+		if (Object.keys(frontmatter).length === 0 || body.trim().length === 0) {
+			console.error(
+				`✗ ${style.id}: not a valid output style (no frontmatter or no body)`,
+			);
+			problems++;
+			continue;
+		}
+		// Advisory, not a failure: upstream is free to rename a style, and the
+		// coordinate id is deliberately independent of it. But a drifted
+		// displayName is what the user reads, so it is worth seeing.
+		const upstreamName = frontmatter.name;
+		const drift =
+			upstreamName && upstreamName !== style.displayName
+				? `  (upstream name is now "${upstreamName}", registry says "${style.displayName}")`
+				: "";
+		console.log(
+			`✓ ${style.id.padEnd(38)} ${String(bytes).padStart(6)} B${drift}`,
+		);
+	}
+
+	console.log(
+		problems === 0
+			? "\nRegistry is clean — safe to commit."
+			: `\n${problems} problem(s). Do NOT commit until they are fixed.`,
+	);
+	return problems;
+}
+
+async function main(): Promise<number> {
+	const { values, positionals } = parseArgs({
+		args: process.argv.slice(2),
+		options: {
+			discover: { type: "boolean", default: false },
+			check: { type: "boolean", default: false },
+		},
+		allowPositionals: true,
+	});
+
+	if (!values.discover && !values.check) {
+		console.error(
+			"usage: bun scripts/verify-community-registry.ts --discover [<repo> <dir>]\n" +
+				"       bun scripts/verify-community-registry.ts --check",
+		);
+		return 1;
+	}
+
+	let problems = 0;
+	if (values.discover) {
+		problems += await runDiscover(positionals[0], positionals[1]);
+	}
+	if (values.check) {
+		problems += await runCheck();
+	}
+	return problems === 0 ? 0 : 1;
+}
+
+if (import.meta.main) {
+	main()
+		.then((code) => process.exit(code))
+		.catch((error) => {
+			console.error(
+				`error: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			process.exit(1);
+		});
+}

package/src/__tests__/active-closure.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test";
+import {
+	type ActiveClosureDeps,
+	loadActiveClosure,
+	selectProfileId,
+} from "../services/active-closure.js";
+import { resolveProfile } from "../services/resolver.js";
+import type {
+	BinRequirement,
+	ProfileManifest,
+	ResolvedClosure,
+} from "../types/index.js";
+
+/**
+ * The CLI and the TUI choose a profile through ONE function. They used to
+ * differ — the CLI inline, the TUI not at all — so an exact pin could never
+ * produce the same state in both.
+ *
+ * Every IO edge is injected; nothing here reads the real manifest, the real
+ * active-profile symlink, or any plugin.json.
+ */
+
+const PROJECT = "/tmp/no-such-project";
+
+function manifest(
+	profiles: ProfileManifest["profiles"],
+	over: Partial<ProfileManifest> = {},
+): ProfileManifest {
+	return { version: 2, profiles, ...over };
+}
+
+const ONE = manifest({
+	default: {
+		name: "default",
+		plugins: { "dev@magus": "latest", "terminal@magus": "5.0.1" },
+		cliTools: { claudish: "latest" },
+	},
+} as ProfileManifest["profiles"]);
+
+const TWO = manifest({
+	frontend: { name: "frontend", plugins: { "dev@magus": "latest" } },
+	backend: { name: "backend", plugins: { "terminal@magus": "latest" } },
+} as ProfileManifest["profiles"]);
+
+/** A plugin.json resolver that fails the test if the screen reads one. */
+const MUST_NOT_READ = async (pluginId: string): Promise<BinRequirement[]> => {
+	throw new Error(`read plugin.json for ${pluginId}`);
+};
+
+describe("selectProfileId", () => {
+	const ids = ["frontend", "backend"];
+
+	test.each([
+		// [explicit, active, expected]
+		["frontend", "backend", "frontend"], // explicit wins
+		[undefined, "backend", "backend"], // then the active one
+		[undefined, null, null], // two profiles, no choice: ambiguous
+		["missing", "backend", "backend"], // unknown explicit is ignored
+		[undefined, "stale", null], // stale active, two profiles: ambiguous
+	] as const)("explicit=%p active=%p → %p", (explicit, active, expected) => {
+		expect(selectProfileId(ids, explicit, active)).toBe(expected);
+	});
+
+	test("a single profile needs no activation", () => {
+		expect(selectProfileId(["default"], undefined, null)).toBe("default");
+	});
+
+	test("a stale active symlink with a single profile picks the single one", () => {
+		// The profile the symlink names was removed from the manifest. The CLI
+		// used to pick the stale name and then fail to resolve it.
+		expect(selectProfileId(["default"], undefined, "removed")).toBe("default");
+	});
+
+	test("no profiles at all selects nothing", () => {
+		expect(selectProfileId([], undefined, null)).toBeNull();
+		expect(selectProfileId([], "x", "y")).toBeNull();
+	});
+});
+
+/** Deps over a fixed manifest and active name, recording every resolve call. */
+function fakeDeps(m: ProfileManifest, active: string | null) {
+	const calls: Array<{
+		id: string;
+		binResolver?: (id: string) => Promise<BinRequirement[]>;
+	}> = [];
+	const deps: Partial<ActiveClosureDeps> = {
+		readManifest: async () => m,
+		activeProfile: async () => active,
+		resolveProfile: async (manifest, id, opts) => {
+			calls.push({ id, binResolver: opts?.binResolver });
+			// The real resolver, but never the real plugin.json reader: when the
+			// caller passed none, a reader that throws stands in for the default.
+			return resolveProfile(manifest, id, {
+				binResolver: opts?.binResolver ?? MUST_NOT_READ,
+			});
+		},
+	};
+	return { deps, calls };
+}
+
+describe("loadActiveClosure", () => {
+	test("resolves the active profile's closure", async () => {
+		const { deps } = fakeDeps(TWO, "backend");
+		const got = await loadActiveClosure(PROJECT, { resolveBins: false, deps });
+		expect(got?.profileId).toBe("backend");
+		expect(got?.closure.plugins).toEqual({ "terminal@magus": "latest" });
+	});
+
+	test("passes the manifest's pins through exactly", async () => {
+		const { deps } = fakeDeps(ONE, null);
+		const got = await loadActiveClosure(PROJECT, { resolveBins: false, deps });
+		expect(got?.closure.plugins).toEqual({
+			"dev@magus": "latest",
+			"terminal@magus": "5.0.1",
+		});
+	});
+
+	test("an invalid manifest is null, not a throw", async () => {
+		const { deps, calls } = fakeDeps(
+			{ version: 1, profiles: {} } as unknown as ProfileManifest,
+			null,
+		);
+		expect(await loadActiveClosure(PROJECT, { deps })).toBeNull();
+		expect(calls).toEqual([]);
+	});
+
+	test("no manifest (readManifest's empty v2) is null", async () => {
+		const { deps } = fakeDeps(manifest({}), null);
+		expect(await loadActiveClosure(PROJECT, { deps })).toBeNull();
+	});
+
+	test("two profiles and none active is null — there is no choice to make", async () => {
+		const { deps, calls } = fakeDeps(TWO, null);
+		expect(await loadActiveClosure(PROJECT, { deps })).toBeNull();
+		expect(calls).toEqual([]);
+	});
+
+	test("a stale active symlink with a single profile resolves the single one", async () => {
+		const { deps } = fakeDeps(ONE, "removed-profile");
+		const got = await loadActiveClosure(PROJECT, { resolveBins: false, deps });
+		expect(got?.profileId).toBe("default");
+	});
+
+	test("resolveBins:false hands resolveProfile a resolver that returns []", async () => {
+		// The Plugins screen needs only pins. The default resolver reads every
+		// declared plugin's plugin.json on each fetch.
+		const { deps, calls } = fakeDeps(ONE, null);
+		const got = await loadActiveClosure(PROJECT, { resolveBins: false, deps });
+		expect(calls).toHaveLength(1);
+		const resolver = calls[0]?.binResolver;
+		expect(resolver).toBeDefined();
+		expect(await resolver?.("dev@magus")).toEqual([]);
+		// No plugin-declared bins; the profile's own cliTools still resolve.
+		expect(got?.closure.bins.map((b) => b.name)).toEqual(["claudish"]);
+	});
+
+	test("resolveBins defaults to true: the real plugin.json resolver is used", async () => {
+		const { deps, calls } = fakeDeps(ONE, null);
+		// MUST_NOT_READ stands in for the default reader, so the default path
+		// shows up as a rejected resolve — which loadActiveClosure reports as null.
+		expect(await loadActiveClosure(PROJECT, { deps })).toBeNull();
+		expect(calls).toHaveLength(1);
+		expect(calls[0]?.binResolver).toBeUndefined();
+	});
+
+	test("any failing edge is null, never a throw", async () => {
+		const boom = async (): Promise<never> => {
+			throw new Error("boom");
+		};
+		for (const deps of [
+			{ readManifest: boom },
+			{ readManifest: async () => ONE, activeProfile: boom },
+			{
+				readManifest: async () => ONE,
+				activeProfile: async () => null,
+				resolveProfile: boom as unknown as (
+					...args: unknown[]
+				) => Promise<ResolvedClosure>,
+			},
+		]) {
+			expect(await loadActiveClosure(PROJECT, { deps })).toBeNull();
+		}
+	});
+});