magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/manifest.ts

@@ -0,0 +1,250 @@
+/**
+ * Team profile manifest (.claude/profiles.json) — read, migrate, validate.
+ *
+ * This is the v2 view over the same project-scoped profiles.json that the TUI's
+ * v1 saved-profiles code (services/profiles.ts) reads. v1 files migrate forward
+ * transparently: a v1 profile (`{name, plugins: Record<string,boolean>}`) is a
+ * structural subset of a v2 manifest entry, so migration is a version bump.
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
+import { validateModelsConfig } from "./models-core.js";
+
+const PROFILES_FILE = "profiles.json";
+
+/** Project-scoped manifest path: <projectPath|cwd>/.claude/profiles.json */
+export function getManifestPath(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", PROFILES_FILE);
+}
+
+/** An empty, valid v2 manifest. */
+export function emptyManifest(): ProfileManifest {
+	return { version: 2, profiles: {} };
+}
+
+/**
+ * Normalize any parsed profiles.json (v1 or v2) into a v2 manifest.
+ * Unknown/missing shapes degrade to an empty manifest rather than throwing —
+ * validation is the caller's job via {@link validateManifest}.
+ */
+export function migrateToV2(raw: unknown): ProfileManifest {
+	if (!raw || typeof raw !== "object") return emptyManifest();
+	const obj = raw as Record<string, unknown>;
+
+	const profilesRaw =
+		obj.profiles && typeof obj.profiles === "object"
+			? (obj.profiles as Record<string, unknown>)
+			: {};
+
+	const profiles: Record<string, ProfileManifestEntry> = {};
+	for (const [id, entry] of Object.entries(profilesRaw)) {
+		if (entry && typeof entry === "object") {
+			// v1 and v2 entries are both accepted as-is; v1's plugins map
+			// (Record<string, boolean>) is valid under v2's widened type.
+			profiles[id] = entry as ProfileManifestEntry;
+		}
+	}
+
+	const manifest: ProfileManifest = { version: 2, profiles };
+	// Only carry strictVersions when enabled, so a committed manifest that
+	// doesn't opt in stays minimal (no spurious `"strictVersions": false`).
+	if (obj.strictVersions === true) manifest.strictVersions = true;
+	return manifest;
+}
+
+/**
+ * Read and migrate the project manifest. Returns an empty v2 manifest if the
+ * file is absent or unreadable.
+ */
+export async function readManifest(
+	projectPath?: string,
+): Promise<ProfileManifest> {
+	const filePath = getManifestPath(projectPath);
+	try {
+		if (await fs.pathExists(filePath)) {
+			return migrateToV2(await fs.readJson(filePath));
+		}
+	} catch {
+		// Corrupt/unreadable — fall through to empty.
+	}
+	return emptyManifest();
+}
+
+/** Write the manifest back to disk (used by `profile sync`, tests). */
+export async function writeManifest(
+	manifest: ProfileManifest,
+	projectPath?: string,
+): Promise<void> {
+	const filePath = getManifestPath(projectPath);
+	await fs.ensureDir(path.dirname(filePath));
+	await fs.writeJson(filePath, manifest, { spaces: 2 });
+}
+
+export interface ManifestValidationError {
+	/** Dotted path to the offending field, e.g. "profiles.frontend.plugins". */
+	path: string;
+	message: string;
+}
+
+/**
+ * Validate a manifest structurally. Returns an empty array when valid.
+ * Strict enough to back `install --check`; does not touch the network or FS.
+ */
+export function validateManifest(
+	manifest: ProfileManifest,
+): ManifestValidationError[] {
+	const errors: ManifestValidationError[] = [];
+
+	if (manifest.version !== 2) {
+		errors.push({
+			path: "version",
+			message: `expected version 2, got ${JSON.stringify(manifest.version)}`,
+		});
+	}
+
+	const ids = Object.keys(manifest.profiles ?? {});
+	if (ids.length === 0) {
+		errors.push({ path: "profiles", message: "no profiles defined" });
+	}
+
+	for (const [id, entry] of Object.entries(manifest.profiles ?? {})) {
+		const base = `profiles.${id}`;
+		if (!entry || typeof entry !== "object") {
+			errors.push({ path: base, message: "profile must be an object" });
+			continue;
+		}
+		if (!entry.name || typeof entry.name !== "string") {
+			errors.push({ path: `${base}.name`, message: "missing name" });
+		}
+		if (entry.plugins !== undefined) {
+			for (const [pluginId, ver] of Object.entries(entry.plugins)) {
+				if (typeof ver !== "string" && typeof ver !== "boolean") {
+					errors.push({
+						path: `${base}.plugins.${pluginId}`,
+						message: "version must be a string or boolean",
+					});
+				}
+				if (!pluginId.includes("@")) {
+					errors.push({
+						path: `${base}.plugins.${pluginId}`,
+						message: "plugin id must be in the form name@marketplace",
+					});
+				}
+			}
+		}
+		if (entry.marketplaces !== undefined) {
+			for (const [mpName, ref] of Object.entries(entry.marketplaces)) {
+				if (ref.source === "github" && !ref.repo) {
+					errors.push({
+						path: `${base}.marketplaces.${mpName}`,
+						message: "github marketplace requires `repo`",
+					});
+				}
+				if (ref.source === "directory" && !ref.path) {
+					errors.push({
+						path: `${base}.marketplaces.${mpName}`,
+						message: "directory marketplace requires `path`",
+					});
+				}
+			}
+		}
+		if (entry.skills !== undefined) {
+			entry.skills.forEach((s, i) => {
+				if (!s.name || !s.repo || !s.path) {
+					errors.push({
+						path: `${base}.skills[${i}]`,
+						message: "skill requires name, repo, and path",
+					});
+				}
+			});
+		}
+		// Model routing is the one field here whose bad value does not degrade:
+		// MEASURED (benches/agent-model-routing, `bogus-model` 5/5), a model the
+		// Agent tool does not accept refuses the spawn outright, so EVERY subagent
+		// dispatch fails for everyone who pulled the manifest. This is the gate
+		// that stops a hand-edited entry reaching a session.
+		if (entry.models !== undefined) {
+			for (const e of validateModelsConfig(entry.models)) {
+				errors.push({
+					path: e.path ? `${base}.models.${e.path}` : `${base}.models`,
+					message: e.message,
+				});
+			}
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Read/modify/write ONE profile entry in the committed manifest.
+ *
+ * Returns false when there is nothing to record against (no profile named, no
+ * manifest file, or no entry for that profile) — all three are normal states,
+ * and `mutate` is not called.
+ *
+ * THROWS when the manifest exists and cannot be read as JSON. `readManifest`
+ * degrades a corrupt file to an empty manifest, which here would mean silently
+ * recording nothing and reporting success — the caller has just written a live
+ * setting the next `magus install` will revert, and would never learn.
+ */
+export async function updateProfileEntry(
+	projectPath: string,
+	profile: string | null,
+	mutate: (entry: ProfileManifestEntry) => void,
+): Promise<boolean> {
+	if (!profile) return false;
+	const filePath = getManifestPath(projectPath);
+	if (!(await fs.pathExists(filePath))) return false;
+
+	// Read directly rather than through readManifest: its `catch` is exactly
+	// what turns a corrupt file into a silent no-op.
+	let raw: unknown;
+	try {
+		raw = await fs.readJson(filePath);
+	} catch (error) {
+		throw new Error(
+			`${filePath} is not valid JSON, refusing to write to it: ${String(error)}`,
+		);
+	}
+
+	const manifest = migrateToV2(raw);
+	const entry = manifest.profiles[profile];
+	if (!entry) return false;
+
+	mutate(entry);
+	entry.updatedAt = new Date().toISOString();
+	await writeManifest(manifest, projectPath);
+	return true;
+}
+
+/**
+ * Merge `patch` into `profiles.<profile>.settings`, optionally removing the
+ * keys named in `unset`.
+ *
+ * Why this exists: `.claude/settings.json` is a symlink into the active
+ * profile's materialized directory, so a live write lands in the right place —
+ * but `materializeProfile` REWRITES that file from the manifest on every
+ * `magus install`, so the live write alone silently regresses. The manifest
+ * is the durable half of every settings write magus makes.
+ */
+export async function mergeManifestSettings(
+	projectPath: string,
+	profile: string | null,
+	patch: Record<string, unknown>,
+	opts: { unset?: readonly string[] } = {},
+): Promise<boolean> {
+	return updateProfileEntry(projectPath, profile, (entry) => {
+		const settings = { ...(entry.settings ?? {}), ...patch };
+		for (const key of opts.unset ?? []) {
+			// The key must be ABSENT, not present-and-undefined: an `= undefined`
+			// assignment still answers `in` checks, so the next call would read it
+			// as already handled and skip work it still owes.
+			delete settings[key];
+		}
+		entry.settings = settings;
+	});
+}

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

@@ -0,0 +1,173 @@
+/**
+ * marketplace-catalog-git.ts — read a marketplace's CURRENT catalog over git,
+ * without touching the checked-out clone.
+ *
+ * Why this exists
+ * ---------------
+ * `autoUpdate: false` is deliberate policy here: plugins are not updated
+ * automatically, the UI merely shows that an update is available. That freezes the
+ * clone at `~/.claude/plugins/marketplaces/<name>`, which is correct — the clone
+ * is the INSTALL SOURCE, and pinning it is the point.
+ *
+ * The mistake was using that same frozen clone as the CATALOG — the answer to
+ * "what version exists upstream". Those are two different jobs riding one
+ * artifact, and pinning the first silently blinded the second: the clone said
+ * terminal 4.1.4, the installed copy was 4.1.4, so the screen reported up to date
+ * while 4.2.0 had shipped.
+ *
+ * `git fetch` updates `refs/remotes/origin/*` and nothing else. The working tree
+ * does not move, HEAD does not move, so installs stay pinned exactly as the policy
+ * intends — and `git show origin/<branch>:.claude-plugin/marketplace.json` then
+ * reads the real upstream catalog. Verified 2026-08-17 against the magus clone:
+ * catalog read as 9.0.3 / terminal 4.2.0 while HEAD stayed at c45ddee.
+ *
+ * It also sidesteps the reason the HTTP path was failing. `raw.githubusercontent.com`
+ * was returning 429; git talks the smart-transport protocol over SSH or HTTPS and
+ * draws on neither that bucket nor the REST budget. So the version check keeps
+ * 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 {
+	type MarketplacePlugin,
+	normalizeCatalogJson,
+} from "./marketplace-catalog.js";
+
+/** Network reach; a wedged fetch must never hold up the screen. */
+const FETCH_TIMEOUT_MS = 15_000;
+/** Local object reads are fast or broken. */
+const LOCAL_TIMEOUT_MS = 5_000;
+
+/**
+ * Resolved per call, honouring CLAUDE_CONFIG_DIR — the same override Claude Code
+ * uses, and the same approach content-drift.ts takes for the same directory.
+ *
+ * Returns null when a test has not chosen a config dir, so an unisolated test
+ * cannot make this function perform a live `git fetch` against the operator's real
+ * marketplace clones. See utils/config-dir.ts.
+ */
+function cloneDir(name: string): string | null {
+	const configDir = claudeConfigDirOrNull();
+	if (!configDir) return null;
+	return path.join(configDir, "plugins", "marketplaces", name);
+}
+
+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 }),
+		);
+	});
+}
+
+/**
+ * Session cache. A catalog cannot change under us mid-session unless the user
+ * explicitly refreshes, and each miss costs a network round trip per marketplace.
+ */
+const catalogCache = new Map<string, MarketplacePlugin[] | null>();
+
+export function clearGitCatalogCache(): void {
+	catalogCache.clear();
+}
+
+/** The branch `origin/HEAD` points at, falling back to `main`. */
+async function defaultBranch(dir: string): Promise<string> {
+	const ref = await git(
+		dir,
+		["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+		LOCAL_TIMEOUT_MS,
+	);
+	const name = ref.out.trim();
+	// "origin/main" → "main"
+	if (ref.ok && name.startsWith("origin/")) return name.slice("origin/".length);
+	return "main";
+}
+
+/**
+ * The marketplace's upstream catalog, or null when it cannot be read honestly.
+ *
+ * Null covers: no clone on disk, not a git repo, no reachable remote, fetch
+ * refused, or a catalog that does not parse. Every one of those must stay
+ * distinguishable from "an empty catalog" — collapsing them is the bug this
+ * module was written to help fix.
+ */
+export async function readCatalogFromRemote(
+	marketplaceName: string,
+): Promise<MarketplacePlugin[] | null> {
+	if (catalogCache.has(marketplaceName)) {
+		return catalogCache.get(marketplaceName) ?? null;
+	}
+
+	const dir = cloneDir(marketplaceName);
+	if (!dir || !fs.existsSync(path.join(dir, ".git"))) {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	const branch = await defaultBranch(dir);
+
+	// Refs only. No merge, no checkout, no working-tree change — this is what
+	// makes the read compatible with `autoUpdate: false`.
+	const fetched = await git(
+		dir,
+		["fetch", "--quiet", "origin", branch],
+		FETCH_TIMEOUT_MS,
+	);
+	if (!fetched.ok) {
+		// A failed fetch may still leave a usable-but-older origin ref from a
+		// previous fetch. That is strictly better than the working tree, but it is
+		// not current, so it is not offered here — the caller's clone fallback
+		// already covers "possibly stale", and labels it as such.
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	const shown = await git(
+		dir,
+		["show", `origin/${branch}:.claude-plugin/marketplace.json`],
+		LOCAL_TIMEOUT_MS,
+	);
+	if (!shown.ok) {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	try {
+		const plugins = normalizeCatalogJson(
+			marketplaceName,
+			JSON.parse(shown.out),
+		);
+		catalogCache.set(marketplaceName, plugins);
+		return plugins;
+	} catch {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+}

package/src/services/marketplace-catalog.ts

@@ -0,0 +1,129 @@
+/**
+ * marketplace-catalog.ts — the catalog shape and its parser, transport-agnostic.
+ *
+ * A marketplace catalog can arrive two ways: over HTTP from
+ * raw.githubusercontent.com (`marketplace-fetcher.ts`) or out of a git remote ref
+ * (`marketplace-catalog-git.ts`). Both must produce byte-identical results — a
+ * catalog that parsed differently depending on how it was fetched would make
+ * version comparisons depend on the transport, which is the same class of bug as
+ * the one that made a failed fetch read as "up to date".
+ *
+ * This module exists so the two transports share one parser without importing
+ * each other. The fetcher needs the git reader as a fallback and the git reader
+ * needs the parser, so putting the parser in either one would make them mutually
+ * dependent.
+ */
+
+import type { PluginRelease } from "../types/index.js";
+import { normalizeReleases } from "./plugin-releases.js";
+
+export interface MarketplacePlugin {
+	name: string;
+	version: string | null;
+	description: string;
+	category?: string;
+	author?: { name: string; email?: string };
+	homepage?: string;
+	tags?: string[];
+	releases?: PluginRelease[];
+	/**
+	 * The plugin's directory inside the marketplace repo, as declared. "" means
+	 * the repo root, which is how every single-plugin marketplace publishes
+	 * ("source": "./").
+	 */
+	source?: string;
+	/**
+	 * Set only when the plugin declares an object source naming a repo other
+	 * than the marketplace's own. Its files live there, not in the marketplace.
+	 */
+	sourceRepo?: string;
+}
+
+// Session-level cache for each marketplace's declared version (from
+// marketplace.json's top-level `metadata.version`), so the TUI can surface a
+// marketplace's version without re-fetching. Only populated for marketplaces that
+// actually declare one.
+const marketplaceVersionCache = new Map<string, string>();
+
+export function clearMarketplaceVersionCache(): void {
+	marketplaceVersionCache.clear();
+}
+
+/**
+ * Returns the version a marketplace declared in its `metadata.version`, if one
+ * was seen during a successful read this session. Returns `undefined` for
+ * marketplaces that declare no version (or haven't been read yet).
+ */
+export function getMarketplaceVersion(
+	marketplaceName: string,
+): string | undefined {
+	return marketplaceVersionCache.get(marketplaceName);
+}
+
+interface RawPlugin {
+	name: string;
+	version?: string | null;
+	description?: string;
+	category?: string;
+	author?: { name: string; email?: string };
+	homepage?: string;
+	tags?: string[];
+	releases?: unknown;
+	source?: string | { source?: string; repo?: string };
+}
+
+/**
+ * Split a manifest `source` into a repo-relative directory and, when the plugin
+ * points at a different repo than the marketplace, that repo.
+ *
+ * Both forms are in use: a string path ("./", "./plugins/dev") and an object
+ * ({"source":"github","repo":"owner/name"}), which addyosmani/agent-skills
+ * publishes. The object form has no path — the plugin is the whole repo.
+ */
+function splitSource(source: RawPlugin["source"]): {
+	source?: string;
+	sourceRepo?: string;
+} {
+	if (typeof source === "string") {
+		return { source: source.replace(/^\.\//, "").replace(/\/+$/, "") };
+	}
+	if (source && typeof source === "object" && typeof source.repo === "string") {
+		return { source: "", sourceRepo: source.repo };
+	}
+	return {};
+}
+
+/** Parse a `marketplace.json` payload into plugin entries. */
+export function normalizeCatalogJson(
+	marketplaceName: string,
+	raw: unknown,
+): MarketplacePlugin[] {
+	const data = (raw ?? {}) as {
+		plugins?: RawPlugin[];
+		metadata?: { version?: string };
+	};
+	const plugins: MarketplacePlugin[] = [];
+
+	const version = data.metadata?.version;
+	if (typeof version === "string" && version.length > 0) {
+		marketplaceVersionCache.set(marketplaceName, version);
+	}
+
+	if (data.plugins && Array.isArray(data.plugins)) {
+		for (const plugin of data.plugins) {
+			plugins.push({
+				name: plugin.name,
+				version: plugin.version || null,
+				description: plugin.description || "",
+				category: plugin.category,
+				author: plugin.author,
+				homepage: plugin.homepage,
+				tags: plugin.tags,
+				releases: normalizeReleases(plugin.releases),
+				...splitSource(plugin.source),
+			});
+		}
+	}
+
+	return plugins;
+}