magus-cli 7.12.2 → 7.14.0

package/src/services/market-ops.ts

@@ -0,0 +1,686 @@
+/**
+ * market-ops.ts — the one path every `magus market` verb takes, CLI and TUI.
+ *
+ * A planner (`planX` in market-ops-repo.ts and market-ops-content.ts) is
+ * read-only and answers a {@link MarketPlan}. {@link applyMarketPlan} is the
+ * only writer: it takes the marketplace's lock, syncs magus's working clone,
+ * plans again from that fresh state, refuses when the `planId` differs from
+ * the one consented to, then runs the plan's steps in order and stops at the
+ * first failure. The working clone is reset and cleaned however it ends.
+ *
+ * `market list` and `market fetch` live here too: list reads, fetch writes
+ * only magus's own working clones.
+ */
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	type Snapshot,
+	acquireMarketLock,
+	cloneUrl,
+	readRemoteState,
+	resetWorkingClone,
+	syncWorkingClone,
+} from "./market-clone.js";
+import {
+	currentVersion,
+	joinRel,
+	pluginDirFor,
+	pluginEntries,
+	pluginRelDir,
+	pluginRootOf,
+} from "./market-layout.js";
+import { localItems } from "./market-local.js";
+import {
+	type TrustedRegistration,
+	isGithubSource,
+	listCompanyMarketplaces,
+} from "./market-registry.js";
+import {
+	MarketError,
+	type MarketErrorCode,
+	type MarketPlan,
+	type MarketResult,
+	type MarketplaceRow,
+	type PlanAnswer,
+	type StepRecord,
+	staleError,
+} from "./market-types.js";
+
+export type MarketCommand = `market ${string}`;
+
+// ─── Exit codes ──────────────────────────────────────────────────────────────
+
+const EXIT_BY_CODE: Partial<Record<MarketErrorCode, number>> = {
+	"gh-auth": 4,
+	"plan-changed": 3,
+	stale: 3,
+	"not-found": 2,
+	ambiguous: 2,
+	"invalid-name": 2,
+};
+
+/** The process exit status for a result. */
+export function exitCodeFor(result: MarketResult, usage = false): number {
+	if (usage) return 2;
+	switch (result.outcome) {
+		case "ok":
+		case "unchanged":
+		case "plugin-newer":
+		case "pull-request":
+			return 0;
+		case "needs-consent":
+		case "stale":
+			return 3;
+		default:
+			return result.error ? (EXIT_BY_CODE[result.error.code] ?? 1) : 1;
+	}
+}
+
+// ─── Results ─────────────────────────────────────────────────────────────────
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** A failure as a result. A `MarketError` keeps its code; anything else is `other`. */
+export function errorResult(
+	command: MarketCommand,
+	error: unknown,
+	extra: Partial<MarketResult> = {},
+	steps: StepRecord[] = [],
+): MarketResult {
+	const e =
+		error instanceof MarketError
+			? error
+			: new MarketError(
+					/claude CLI not found/i.test(errorText(error))
+						? "claude-missing"
+						: "other",
+					errorText(error),
+				);
+	const stale = e.code === "stale";
+	const changed = e.code === "plan-changed";
+	return {
+		...extra,
+		command,
+		outcome: stale ? "stale" : changed ? "needs-consent" : "failed",
+		message: e.message,
+		...(stale ? { stale: true } : {}),
+		steps,
+		error: {
+			code: e.code,
+			message: e.message,
+			...(e.fix ? { fix: e.fix } : {}),
+		},
+	};
+}
+
+/** Exit status of a usage error carried by a `MarketError`. */
+export function errorExit(error: unknown): number | undefined {
+	return error instanceof MarketError ? error.exit : undefined;
+}
+
+/** A planner's answer for an error. */
+export function planError(command: MarketCommand, error: unknown): PlanAnswer {
+	if (error instanceof MarketError) {
+		return { kind: "error", command, error };
+	}
+	return {
+		kind: "error",
+		command,
+		error: new MarketError("other", errorText(error)),
+	};
+}
+
+/** The result for a plan nobody has consented to: nothing written, exit 3. */
+export function needsConsent(plan: MarketPlan): MarketResult {
+	return {
+		command: plan.command,
+		outcome: "needs-consent",
+		message: "Nothing was changed: this plan needs consent (--yes=<planId>).",
+		planId: plan.planId,
+		...plan.summary,
+		plan: plan.lines,
+		steps: [],
+	};
+}
+
+// ─── planId ──────────────────────────────────────────────────────────────────
+
+function stable(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(stable);
+	if (value && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const key of Object.keys(value as object).sort()) {
+			const v = (value as Record<string, unknown>)[key];
+			if (v !== undefined) out[key] = stable(v);
+		}
+		return out;
+	}
+	return value;
+}
+
+/** The hash of every material fact of a plan; consent binds to it. */
+export function computePlanId(facts: Record<string, unknown>): string {
+	return createHash("sha256")
+		.update(JSON.stringify(stable(facts)))
+		.digest("hex")
+		.slice(0, 16);
+}
+
+// ─── Resolving names ─────────────────────────────────────────────────────────
+
+/** The company marketplace named `name`, or `not-found` (exit 2). */
+export async function companyByName(
+	name: string,
+): Promise<TrustedRegistration> {
+	const all = await listCompanyMarketplaces();
+	const found = all.find((m) => m.name === name);
+	if (found) return found;
+	throw new MarketError(
+		"not-found",
+		`${name} is not a company marketplace on this machine`,
+		all.length > 0
+			? `company marketplaces here: ${all.map((m) => m.name).join(", ")}`
+			: "run `magus market create` or `magus market connect` first",
+	);
+}
+
+/**
+ * Split `plugin@marketplace`. The `@marketplace` part may be left out when
+ * this machine has exactly one company marketplace.
+ */
+export async function resolvePluginRef(
+	ref: string,
+): Promise<{ plugin: string; m: TrustedRegistration }> {
+	const at = ref.lastIndexOf("@");
+	if (at > 0) {
+		return {
+			plugin: ref.slice(0, at),
+			m: await companyByName(ref.slice(at + 1)),
+		};
+	}
+	const all = await listCompanyMarketplaces();
+	if (all.length === 1 && all[0]) return { plugin: ref, m: all[0] };
+	if (all.length === 0) {
+		throw new MarketError(
+			"not-found",
+			"There is no company marketplace on this machine",
+			"run `magus market create` or `magus market connect` first",
+		);
+	}
+	throw new MarketError(
+		"ambiguous",
+		`More than one company marketplace is on this machine (${all.map((m) => m.name).join(", ")})`,
+		`name it: ${ref}@<marketplace>`,
+	);
+}
+
+/**
+ * The marketplace as GitHub has it now, or a `stale` error: a write verb
+ * decides nothing from state older than GitHub's.
+ */
+export async function freshSnapshot(m: TrustedRegistration): Promise<Snapshot> {
+	const state = await readRemoteState(m);
+	if (state.fresh) return state.snapshot;
+	if (state.failure === "auth") {
+		throw new MarketError(
+			"gh-auth",
+			`Could not read ${m.name}: ${state.reason}`,
+			state.fix,
+		);
+	}
+	if (state.failure === "no-network") {
+		throw new MarketError(
+			"no-network",
+			`Could not reach ${m.name}'s repository`,
+		);
+	}
+	throw staleError([m.name], `${m.name}: ${state.reason}`, state.fix);
+}
+
+/** The manifest at the snapshot, as an object. */
+export async function manifestAt(
+	snap: Snapshot,
+	label: string,
+): Promise<Record<string, unknown>> {
+	const manifest = await snap.readJson(".claude-plugin/marketplace.json");
+	if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+		throw new MarketError("other", `${label} holds no marketplace manifest`);
+	}
+	return manifest as Record<string, unknown>;
+}
+
+// ─── Apply ───────────────────────────────────────────────────────────────────
+
+export interface ApplyOptions {
+	/** The planId consented to; null applies whatever the fresh plan is. */
+	approved: string | null;
+	cwd: string;
+	/** Called as each step settles. */
+	onStep?: (step: StepRecord, label: string) => void;
+}
+
+/**
+ * Apply a plan. Lock, sync, plan again, compare the planId, run the steps.
+ * A changed plan writes nothing and answers `needs-consent` with
+ * `error.code: "plan-changed"` and the fresh plan.
+ */
+export async function applyMarketPlan(
+	plan: MarketPlan,
+	opts: ApplyOptions,
+): Promise<MarketResult> {
+	const steps: StepRecord[] = [];
+	let release: (() => void) | null = null;
+	let synced: { dir: string; branch: string | null } | null = null;
+	let wroteOutside = false;
+	const lockName = plan.sync?.name ?? plan.lock;
+	try {
+		if (lockName) release = await acquireMarketLock(lockName);
+		if (plan.sync) {
+			synced = await syncWorkingClone(plan.sync.name, plan.sync.url);
+		}
+		const fresh = await plan.replan();
+		if (fresh.kind === "result") return { ...fresh.result, steps };
+		if (fresh.kind === "error") {
+			return errorResult(fresh.command, fresh.error, {}, steps);
+		}
+		const p = fresh.plan;
+		if (opts.approved !== null && p.planId !== opts.approved) {
+			return {
+				command: p.command,
+				outcome: "needs-consent",
+				message: "The plan changed since it was shown — nothing was changed.",
+				planId: p.planId,
+				...p.summary,
+				plan: p.lines,
+				steps,
+				error: {
+					code: "plan-changed",
+					message: "The plan changed since it was shown",
+					fix: "review the new plan, then run again with its planId",
+				},
+			};
+		}
+		let result: MarketResult = {
+			command: p.command,
+			outcome: "ok",
+			message: p.doneMessage,
+			planId: p.planId,
+			...p.summary,
+			plan: p.lines,
+			steps,
+		};
+		const ctx = { cwd: opts.cwd, clone: synced?.dir ?? null };
+		for (let i = 0; i < p.steps.length; i++) {
+			const step = p.steps[i];
+			if (!step) continue;
+			try {
+				const out = await step.run(ctx);
+				if (step.outside && !out?.skipped) wroteOutside = true;
+				const record: StepRecord = {
+					id: step.id,
+					status: out?.skipped ? "skipped" : "done",
+					...(out?.detail ? { detail: out.detail } : {}),
+				};
+				steps.push(record);
+				opts.onStep?.(record, step.label);
+				if (out?.patch) result = { ...result, ...out.patch, steps };
+				if (out?.stop) {
+					for (const rest of p.steps.slice(i + 1)) {
+						steps.push({ id: rest.id, status: "skipped" });
+					}
+					break;
+				}
+			} catch (error) {
+				if (error instanceof MarketError && error.outsideWrite) {
+					wroteOutside = true;
+				}
+				const record: StepRecord = {
+					id: step.id,
+					status: "failed",
+					detail: errorText(error),
+				};
+				steps.push(record);
+				opts.onStep?.(record, step.label);
+				for (const rest of p.steps.slice(i + 1)) {
+					steps.push({ id: rest.id, status: "skipped" });
+				}
+				const failed = errorResult(p.command, error, result, steps);
+				// "Nothing changed" only while every write so far stayed inside
+				// magus's own working clone.
+				if (!wroteOutside && failed.error?.code !== "plan-changed") {
+					failed.message = `${failed.message} — nothing changed`;
+				}
+				// GitHub moved while this ran (a rejected non-fast-forward push):
+				// nothing was pushed, and the answer carries the plan as it now
+				// stands, for a fresh consent.
+				if (failed.error?.code === "plan-changed" && plan.sync) {
+					try {
+						synced = await syncWorkingClone(plan.sync.name, plan.sync.url);
+						const again = await p.replan();
+						if (again.kind === "plan") {
+							return {
+								...failed,
+								...again.plan.summary,
+								planId: again.plan.planId,
+								plan: again.plan.lines,
+								steps,
+							};
+						}
+					} catch {
+						// The failure stands without a fresh plan.
+					}
+				}
+				return failed;
+			}
+		}
+		return result;
+	} catch (error) {
+		return errorResult(plan.command, error, {}, steps);
+	} finally {
+		if (synced) {
+			try {
+				await resetWorkingClone(synced.dir, synced.branch);
+			} catch {
+				// The next sync resets it again.
+			}
+		}
+		release?.();
+	}
+}
+
+// ─── list ────────────────────────────────────────────────────────────────────
+
+function readJsonFile(file: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The company a marketplace belongs to: its manifest's `owner.name`, else the
+ * GitHub owner of its source. Undefined for a non-GitHub source whose
+ * manifest names no owner.
+ */
+export function companyOf(
+	manifest: unknown,
+	source: string,
+): string | undefined {
+	const owner =
+		manifest && typeof manifest === "object" && !Array.isArray(manifest)
+			? (manifest as { owner?: unknown }).owner
+			: undefined;
+	const name =
+		owner && typeof owner === "object"
+			? (owner as { name?: unknown }).name
+			: undefined;
+	if (typeof name === "string" && name.trim()) return name.trim();
+	if (isGithubSource(source)) return source.split("/")[0] || undefined;
+	return undefined;
+}
+
+/** The plugins and skills of a marketplace as Claude Code's copy holds them. */
+function rowFor(m: TrustedRegistration): MarketplaceRow {
+	const row: MarketplaceRow = {
+		name: m.name,
+		repo: m.source,
+		scope: "user",
+		plugins: [],
+	};
+	const fallback = companyOf(null, m.source);
+	if (fallback) row.company = fallback;
+	if (!m.location) return row;
+	const manifest = readJsonFile(
+		path.join(m.location, ".claude-plugin", "marketplace.json"),
+	);
+	const company = companyOf(manifest, m.source);
+	if (company) row.company = company;
+	const root = pluginRootOf(manifest);
+	for (const entry of pluginEntries(manifest)) {
+		const dir = pluginDirFor(m.location, entry.source, root);
+		const pluginJson = dir
+			? readJsonFile(path.join(dir, ".claude-plugin", "plugin.json"))
+			: null;
+		let skills: string[] = [];
+		if (dir) {
+			try {
+				skills = fs
+					.readdirSync(path.join(dir, "skills"), { withFileTypes: true })
+					.filter(
+						(d) =>
+							d.isDirectory() &&
+							fs.existsSync(path.join(dir, "skills", d.name, "SKILL.md")),
+					)
+					.map((d) => d.name)
+					.sort();
+			} catch {
+				skills = [];
+			}
+		}
+		row.plugins.push({
+			name: entry.name,
+			version: currentVersion(pluginJson, entry) ?? "0.0.0",
+			skills,
+		});
+	}
+	return row;
+}
+
+/** Every plugin name among `marketplaces`. */
+export function companyPluginNames(
+	marketplaces: ReadonlyArray<{ plugins: MarketplaceRow["plugins"] }>,
+): Set<string> {
+	return new Set(marketplaces.flatMap((m) => m.plugins.map((p) => p.name)));
+}
+
+/** Every skill name a company plugin among `marketplaces` holds. */
+export function companySkillNames(
+	marketplaces: ReadonlyArray<{ plugins: MarketplaceRow["plugins"] }>,
+): Set<string> {
+	return new Set(
+		marketplaces.flatMap((m) => m.plugins.flatMap((p) => p.skills)),
+	);
+}
+
+/**
+ * `market list`: every company marketplace here with its plugins, and the
+ * skills and plugin folders here that none of them holds. Read-only.
+ */
+export async function marketList(
+	cwd: string = process.cwd(),
+): Promise<MarketResult> {
+	const marketplaces = (await listCompanyMarketplaces()).map(rowFor);
+	const local = await localItems(
+		cwd,
+		companySkillNames(marketplaces),
+		companyPluginNames(marketplaces),
+	);
+	return {
+		command: "market list",
+		outcome: "ok",
+		message:
+			marketplaces.length === 0
+				? "No company marketplaces on this machine"
+				: `${marketplaces.length} company marketplace${marketplaces.length === 1 ? "" : "s"} on this machine`,
+		marketplaces,
+		local,
+		steps: [],
+	};
+}
+
+// ─── overview ────────────────────────────────────────────────────────────────
+
+/** How current the overview of one marketplace is. */
+export type OverviewFreshness =
+	/** At GitHub's commit. */
+	| "fresh"
+	/** Read from an older local copy, or from nothing; `reason` says which. */
+	| "stale";
+
+/** One company marketplace as the market screens show it. */
+export interface MarketOverviewEntry {
+	name: string;
+	/** The normalised source: `owner/repo`, a URL, or a path. */
+	repo: string;
+	scope: "user";
+	freshness: OverviewFreshness;
+	/** Why the overview is not current, in the user's words; empty when fresh. */
+	reason: string;
+	/** What to do about it; empty when fresh. */
+	fix: string;
+	/** The commit the plugins were read at, when a local copy had one. */
+	commit: string | null;
+	/** The company it belongs to, as {@link companyOf} reads it. */
+	company?: string;
+	plugins: MarketplaceRow["plugins"];
+}
+
+/** The plugins of a marketplace snapshot, with their versions and skills. */
+async function pluginsAt(
+	snap: Snapshot,
+	manifest: Record<string, unknown>,
+): Promise<MarketplaceRow["plugins"]> {
+	const root = pluginRootOf(manifest);
+	const out: MarketplaceRow["plugins"] = [];
+	for (const entry of pluginEntries(manifest)) {
+		const dir = pluginRelDir(entry.source, root);
+		let pluginJson: unknown = null;
+		const skills: string[] = [];
+		if (dir !== null) {
+			try {
+				pluginJson = await snap.readJson(
+					joinRel(dir, ".claude-plugin", "plugin.json"),
+				);
+			} catch {
+				pluginJson = null;
+			}
+			const prefix = joinRel(dir, "skills", "");
+			for (const file of snap.entries.keys()) {
+				if (!file.startsWith(`${prefix}/`)) continue;
+				const rest = file.slice(prefix.length + 1).split("/");
+				if (rest.length === 2 && rest[1] === "SKILL.md" && rest[0]) {
+					skills.push(rest[0]);
+				}
+			}
+		}
+		out.push({
+			name: entry.name,
+			version: currentVersion(pluginJson, entry) ?? "0.0.0",
+			skills: skills.sort(),
+		});
+	}
+	return out;
+}
+
+/**
+ * Every company marketplace here, with its plugins and skills as GitHub has
+ * them now when a local copy is at GitHub's commit, else as the newest local
+ * copy has them, marked stale. Read-only: nothing is cloned, fetched, reset
+ * or locked — the market screens open with this.
+ */
+export async function marketOverview(): Promise<MarketOverviewEntry[]> {
+	const out: MarketOverviewEntry[] = [];
+	for (const m of await listCompanyMarketplaces()) {
+		const state = await readRemoteState(m);
+		const entry: MarketOverviewEntry = {
+			name: m.name,
+			repo: m.source,
+			scope: "user",
+			freshness: state.fresh ? "fresh" : "stale",
+			reason: state.fresh ? "" : state.reason,
+			fix: state.fresh ? "" : state.fix,
+			commit: state.snapshot?.commit ?? null,
+			plugins: [],
+		};
+		let fromSnapshot = false;
+		if (state.snapshot) {
+			try {
+				const manifest = await manifestAt(state.snapshot, m.name);
+				entry.plugins = await pluginsAt(state.snapshot, manifest);
+				const company = companyOf(manifest, m.source);
+				if (company) entry.company = company;
+				fromSnapshot = true;
+			} catch {
+				fromSnapshot = false;
+			}
+		}
+		if (!fromSnapshot) {
+			const row = rowFor(m);
+			entry.plugins = row.plugins;
+			if (row.company) entry.company = row.company;
+		}
+		out.push(entry);
+	}
+	return out;
+}
+
+// ─── fetch ───────────────────────────────────────────────────────────────────
+
+/**
+ * `market fetch [<m>]`: bring magus's working clones up to GitHub. Writes
+ * nothing else, so it needs no consent. Given several names (the ones a
+ * `stale` error carries), fetches only those; given none, every one.
+ */
+export async function marketFetch(
+	only?: string | readonly string[],
+	onStep?: ApplyOptions["onStep"],
+): Promise<MarketResult> {
+	const command: MarketCommand = "market fetch";
+	const names = typeof only === "string" ? [only] : (only ?? []);
+	const name = names.length === 1 ? names[0] : undefined;
+	let targets: TrustedRegistration[];
+	try {
+		targets =
+			names.length > 0
+				? await Promise.all(names.map((n) => companyByName(n)))
+				: await listCompanyMarketplaces();
+	} catch (error) {
+		return errorResult(command, error);
+	}
+	const steps: StepRecord[] = [];
+	let firstError: MarketError | null = null;
+	for (const m of targets) {
+		let release: (() => void) | null = null;
+		const id = `fetch:${m.name}`;
+		try {
+			release = await acquireMarketLock(m.name);
+			const synced = await syncWorkingClone(m.name, cloneUrl(m.source));
+			const record: StepRecord = {
+				id,
+				status: "done",
+				detail: synced.commit ? synced.commit.slice(0, 7) : "empty",
+			};
+			steps.push(record);
+			onStep?.(record, `fetched ${m.name}`);
+		} catch (error) {
+			const e =
+				error instanceof MarketError
+					? error
+					: new MarketError("other", errorText(error));
+			if (!firstError || e.code === "gh-auth") firstError = e;
+			const record: StepRecord = { id, status: "failed", detail: e.message };
+			steps.push(record);
+			onStep?.(record, `fetch ${m.name}`);
+		} finally {
+			release?.();
+		}
+	}
+	if (firstError) {
+		return errorResult(command, firstError, {}, steps);
+	}
+	return {
+		command,
+		outcome: "ok",
+		message:
+			targets.length === 0
+				? "No company marketplaces on this machine"
+				: `Up to date with GitHub: ${targets.map((m) => m.name).join(", ")}`,
+		...(name ? { marketplace: name } : {}),
+		steps,
+	};
+}