magus-cli 7.12.2 → 7.14.0

package/src/services/market-registry.ts

@@ -0,0 +1,382 @@
+/**
+ * market-registry.ts — company marketplaces on this machine.
+ *
+ * A marketplace is a company marketplace here when two facts agree:
+ * - its manifest carries the marker (`market-marker.ts`) — the repository's
+ *   own statement;
+ * - its name and source are on this machine's trust list — this machine's
+ *   decision, made by `market create`/`connect` or by a project profile
+ *   `magus install`/`update` acted on.
+ * The marker alone is not enough: a repository must not be able to rank itself
+ * above magus, or become a publish target, by committing a field.
+ *
+ * The trust list is magus's own file, `<claude config dir>/magus-market/trusted.json`.
+ * Claude Code's registry (`plugins/known_marketplaces.json`) is only ever read
+ * here.
+ *
+ * Reads resolve the config dir through `claudeConfigDirOrNull`, so a test that
+ * has not chosen one reads nothing instead of the operator's real state.
+ * Writes resolve it through `requireClaudeConfigDir`.
+ */
+
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import fs from "fs-extra";
+import { getMarketplaceByName } from "../data/marketplaces.js";
+import type { ProfileMarketplaceRef } from "../types/index.js";
+import {
+	claudeConfigDirOrNull,
+	requireClaudeConfigDir,
+} from "../utils/config-dir.js";
+import { readMarker } from "./market-marker.js";
+
+export const TRUST_SCHEMA = 1;
+
+/** How a marketplace came to be trusted on this machine. */
+export type TrustVia = "create" | "connect" | "profile";
+
+export interface TrustEntry {
+	/** The normalised source ({@link normaliseSource}). */
+	source: string;
+	via: TrustVia;
+}
+
+export interface TrustFile {
+	schema: number;
+	marketplaces: Record<string, TrustEntry>;
+}
+
+/** The result of {@link trust}. */
+export type TrustOutcome =
+	/** Newly put on the list. */
+	| "added"
+	/** Already on the list with the same source; nothing written. */
+	| "exists"
+	/** On the list with a different source; nothing written. */
+	| "conflict";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// ─── Sources ─────────────────────────────────────────────────────────────────
+
+/** A GitHub `owner/repo`. Names start with a letter or digit, never a dot. */
+const GITHUB_SLUG = /^([A-Za-z0-9][A-Za-z0-9-]*)\/([A-Za-z0-9_.-]+)$/;
+
+/** GitHub as a URL host, in each form git accepts. */
+const GITHUB_URL =
+	/^(?:(?:https?|git|ssh|git\+ssh):\/\/(?:[^@/]+@)?github\.com(?::\d+)?\/|[^@/\s]+@github\.com:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/i;
+
+function stripGitSuffix(repo: string): string {
+	return repo.replace(/\.git$/, "");
+}
+
+/** True for a normalised source that is a GitHub `owner/repo`. */
+export function isGithubSource(source: string): boolean {
+	return GITHUB_SLUG.test(source) && !source.startsWith(".");
+}
+
+/**
+ * One spelling per source, so two spellings of the same repository compare
+ * equal:
+ * - a GitHub URL (https, ssh, `git@github.com:`) or a bare `owner/repo` →
+ *   `owner/repo`, without `.git`;
+ * - any other URL → the URL as given (trailing slash removed);
+ * - a path → absolute, a relative one resolved against `baseDir` (the project
+ *   root, for a path in a profile), then its real path when it exists.
+ */
+export function normaliseSource(source: string, baseDir?: string): string {
+	const raw = source.trim();
+	const gh = GITHUB_URL.exec(raw);
+	if (gh?.[1] && gh[2]) return `${gh[1]}/${stripGitSuffix(gh[2])}`;
+	const slug = GITHUB_SLUG.exec(raw);
+	if (slug?.[1] && slug[2] && !raw.startsWith(".")) {
+		return `${slug[1]}/${stripGitSuffix(slug[2])}`;
+	}
+	// Any URL: scheme://… or scp-like user@host:path. A leading `-` is never
+	// a URL: it would reach git as an option, so it resolves as a path below.
+	if (
+		/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw) ||
+		/^[^-@/\s][^@/\s]*@[^:/\s]+:/.test(raw)
+	) {
+		return raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
+	}
+	const absolute = path.resolve(baseDir ?? process.cwd(), raw);
+	try {
+		return fs.realpathSync(absolute);
+	} catch {
+		return absolute;
+	}
+}
+
+/**
+ * Two normalised sources name the same repository. GitHub treats owner and
+ * repository names case-insensitively, so `owner/repo` does too; paths and
+ * other URLs compare exactly.
+ */
+export function sameSource(a: string, b: string): boolean {
+	if (a === b) return true;
+	if (isGithubSource(a) && isGithubSource(b)) {
+		return a.toLowerCase() === b.toLowerCase();
+	}
+	return false;
+}
+
+/** A profile's marketplace ref as a normalised source, or null when it names none. */
+export function refSource(
+	ref: ProfileMarketplaceRef,
+	projectRoot?: string,
+): string | null {
+	if (ref.source === "github") {
+		return ref.repo ? normaliseSource(ref.repo) : null;
+	}
+	return ref.path ? normaliseSource(ref.path, projectRoot) : null;
+}
+
+// ─── Claude Code's registry (read only) ──────────────────────────────────────
+
+interface KnownEntry {
+	source?: {
+		source?: string;
+		repo?: string;
+		url?: string;
+		path?: string;
+	};
+	installLocation?: string;
+}
+
+/** `known_marketplaces.json`, or `{}` when it is absent, unreadable or not an object. */
+async function readKnown(): Promise<Record<string, KnownEntry>> {
+	const root = claudeConfigDirOrNull();
+	if (!root) return {};
+	const file = path.join(root, "plugins", "known_marketplaces.json");
+	try {
+		const parsed: unknown = await fs.readJson(file);
+		return isRecord(parsed) ? (parsed as Record<string, KnownEntry>) : {};
+	} catch {
+		return {};
+	}
+}
+
+/** A registry entry's source, normalised; null when the entry names none. */
+function entrySource(entry: KnownEntry): string | null {
+	const s = entry.source;
+	if (!s) return null;
+	if (s.repo) return normaliseSource(s.repo);
+	if (s.url) return normaliseSource(s.url);
+	if (s.path) return normaliseSource(s.path);
+	return null;
+}
+
+/**
+ * Where this machine's registration of `name` comes from, normalised, or null
+ * when the marketplace is not registered.
+ */
+export async function registeredSource(name: string): Promise<string | null> {
+	const entry = (await readKnown())[name];
+	return entry ? entrySource(entry) : null;
+}
+
+/**
+ * True when this machine's registration of `name` reads a manifest carrying
+ * the company marker: the clone for a git source, the directory itself for a
+ * `directory` source. False when it is not registered or cannot be read.
+ */
+export async function registeredMarker(name: string): Promise<boolean> {
+	const entry = (await readKnown())[name];
+	if (!entry) return false;
+	const dir = entryLocation(name, entry);
+	if (!dir) return false;
+	try {
+		return readMarker(
+			await fs.readJson(path.join(dir, ".claude-plugin", "marketplace.json")),
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The registered marketplaces a profile can record for teammates: each name
+ * mapped to a `github` ref, for every registration whose source is GitHub
+ * (or a git URL on github.com) and whose name is not one of magus's default
+ * marketplaces. Other hosting is not recorded. Read once per caller and passed
+ * down; never writes.
+ */
+export async function registryLookup(): Promise<
+	ReadonlyMap<string, ProfileMarketplaceRef>
+> {
+	const out = new Map<string, ProfileMarketplaceRef>();
+	for (const [name, entry] of Object.entries(await readKnown())) {
+		if (getMarketplaceByName(name)) continue;
+		const source = entrySource(entry);
+		if (!source || !isGithubSource(source)) continue;
+		out.set(name, { source: "github", repo: source });
+	}
+	return out;
+}
+
+// ─── The trust list ──────────────────────────────────────────────────────────
+
+function trustFile(root: string): string {
+	return path.join(root, "magus-market", "trusted.json");
+}
+
+function parseTrust(parsed: unknown): TrustFile {
+	const out: TrustFile = { schema: TRUST_SCHEMA, marketplaces: {} };
+	if (!isRecord(parsed) || !isRecord(parsed.marketplaces)) return out;
+	for (const [name, value] of Object.entries(parsed.marketplaces)) {
+		if (!isRecord(value) || typeof value.source !== "string") continue;
+		const via =
+			value.via === "create" ||
+			value.via === "connect" ||
+			value.via === "profile"
+				? value.via
+				: "profile";
+		out.marketplaces[name] = { source: value.source, via };
+	}
+	return out;
+}
+
+/** The trust list; empty when absent or unreadable. */
+export async function readTrust(): Promise<TrustFile> {
+	const root = claudeConfigDirOrNull();
+	if (!root) return { schema: TRUST_SCHEMA, marketplaces: {} };
+	try {
+		return parseTrust(await fs.readJson(trustFile(root)));
+	} catch {
+		return { schema: TRUST_SCHEMA, marketplaces: {} };
+	}
+}
+
+/**
+ * The trust list as it stands on disk, for a writer. Absent reads as empty; a
+ * file that exists and does not parse throws, so a writer never replaces a
+ * list it could not read.
+ */
+async function readTrustForWrite(file: string): Promise<TrustFile> {
+	if (!(await fs.pathExists(file))) {
+		return { schema: TRUST_SCHEMA, marketplaces: {} };
+	}
+	const raw = await fs.readFile(file, "utf8");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(
+			`The list of company marketplaces on this machine cannot be read (${file}) — fix or delete it, then run the command again`,
+		);
+	}
+	return parseTrust(parsed);
+}
+
+async function writeTrust(file: string, data: TrustFile): Promise<void> {
+	await fs.ensureDir(path.dirname(file));
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	await fs.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`);
+	await fs.rename(tmp, file);
+}
+
+/**
+ * Put `name` on the trust list with `source` (normalised first). An entry for
+ * the name with a different source is never overwritten: that is a conflict.
+ */
+export async function trust(
+	name: string,
+	source: string,
+	via: TrustVia,
+): Promise<TrustOutcome> {
+	const file = trustFile(requireClaudeConfigDir());
+	const data = await readTrustForWrite(file);
+	const normalised = normaliseSource(source);
+	const existing = data.marketplaces[name];
+	if (existing) {
+		return sameSource(existing.source, normalised) ? "exists" : "conflict";
+	}
+	data.marketplaces[name] = { source: normalised, via };
+	await writeTrust(file, data);
+	return "added";
+}
+
+/** Take `name` off the trust list. True when it was on it. */
+export async function untrust(name: string): Promise<boolean> {
+	const file = trustFile(requireClaudeConfigDir());
+	const data = await readTrustForWrite(file);
+	if (!Object.hasOwn(data.marketplaces, name)) return false;
+	delete data.marketplaces[name];
+	await writeTrust(file, data);
+	return true;
+}
+
+/** True when `name` is on the trust list with a source equal to `source`. */
+export function isTrustedIn(
+	list: TrustFile,
+	name: string,
+	source: string | null | undefined,
+): boolean {
+	const entry = list.marketplaces[name];
+	return !!entry && !!source && sameSource(entry.source, source);
+}
+
+/** A trusted company marketplace as this machine registers it. */
+export interface TrustedRegistration {
+	name: string;
+	/** Claude Code's source type: `github`, `git`, `directory`, … */
+	sourceType: string;
+	source: string;
+	/**
+	 * Where Claude Code reads this marketplace on disk: its clone for a git
+	 * source, the directory itself for a `directory` source. Null when no
+	 * config dir is chosen.
+	 */
+	location: string | null;
+}
+
+/** Where Claude Code reads a registered marketplace on disk. */
+function entryLocation(name: string, entry: KnownEntry): string | null {
+	const root = claudeConfigDirOrNull();
+	if (!root) return null;
+	return (
+		entry.installLocation ||
+		(entry.source?.source === "directory" ? entry.source.path : undefined) ||
+		path.join(root, "plugins", "marketplaces", name)
+	);
+}
+
+/**
+ * The trust list joined with Claude Code's registry: every trusted name that
+ * is registered here from the trusted source, whatever the source type.
+ */
+export async function trustedRegistrations(): Promise<TrustedRegistration[]> {
+	const [list, known] = await Promise.all([readTrust(), readKnown()]);
+	const out: TrustedRegistration[] = [];
+	for (const name of Object.keys(list.marketplaces)) {
+		const entry = known[name];
+		if (!entry) continue;
+		const source = entrySource(entry);
+		if (!isTrustedIn(list, name, source) || !source) continue;
+		out.push({
+			name,
+			sourceType: entry.source?.source ?? "",
+			source,
+			location: entryLocation(name, entry),
+		});
+	}
+	return out;
+}
+
+/**
+ * The company marketplaces on this machine: trusted, registered from the
+ * trusted source, and carrying the marker in the copy Claude Code reads.
+ * Read-only.
+ */
+export async function listCompanyMarketplaces(): Promise<
+	TrustedRegistration[]
+> {
+	const out: TrustedRegistration[] = [];
+	for (const r of await trustedRegistrations()) {
+		if (await registeredMarker(r.name)) out.push(r);
+	}
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/services/market-types.ts

@@ -0,0 +1,268 @@
+/**
+ * market-types.ts — the shapes every `magus market` verb shares.
+ *
+ * `MarketResult` is the JSON contract: one object, printed as the last line of
+ * stdout under `--json`, and the value the text renderer and the TUI read.
+ * `MarketPlan` is what a planner answers: read-only facts, the plain-words
+ * plan, its `planId`, and the steps an apply runs.
+ */
+
+export type MarketOutcome =
+	| "ok"
+	| "unchanged"
+	| "plugin-newer"
+	| "pull-request"
+	| "needs-consent"
+	| "stale"
+	| "partial"
+	| "failed";
+
+export type MarketErrorCode =
+	| "gh-missing"
+	| "gh-auth"
+	| "no-access"
+	| "no-network"
+	| "conflict"
+	| "no-base"
+	| "name-taken"
+	| "not-found"
+	| "ambiguous"
+	| "invalid-name"
+	| "external-plugin"
+	| "claude-missing"
+	| "validate-failed"
+	| "locked"
+	| "not-company"
+	| "fork-not-allowed"
+	| "install-failed"
+	| "plan-changed"
+	| "stale"
+	| "timeout"
+	| "signing-timeout"
+	| "other";
+
+/** A step's id, e.g. `commit`, `deliver`, `fetch:acme`. */
+export type StepId = string;
+
+export type FileChange = "added" | "modified" | "deleted";
+
+export type NotPublishedReason =
+	| "dotfile"
+	| "node_modules"
+	| "symlink"
+	| "ignored-here"
+	| "ignored-by-marketplace";
+
+export type DeliveryTarget = "push-or-pr" | "fork-pr";
+
+export type InstallScope = "user" | "project" | "local";
+
+export interface MarketplaceRow {
+	name: string;
+	repo: string;
+	/**
+	 * The company it belongs to: the manifest's `owner.name`, else the GitHub
+	 * owner of its source. Absent when neither names one.
+	 */
+	company?: string;
+	scope: "user";
+	plugins: Array<{ name: string; version: string; skills: string[] }>;
+}
+
+/**
+ * A skill or plugin folder on this machine that is not part of any company
+ * marketplace: one of this project's or your USER skills, or a plugin folder
+ * among them (one holding `.claude-plugin/plugin.json`).
+ */
+export interface LocalItem {
+	kind: "skill" | "plugin";
+	/** The folder's name; for a plugin, its `plugin.json` name when it has one. */
+	name: string;
+	scope: "project" | "user";
+	/** The folder, absolute. */
+	path: string;
+}
+
+export interface SkillStatusRow {
+	skill: string;
+	from: "project" | "user";
+	path: string;
+	owner: string | null;
+	owners?: string[];
+	state:
+		| "edited"
+		| "same"
+		| "plugin-newer"
+		| "conflict"
+		| "no-base"
+		| "not-checked"
+		| "ambiguous"
+		| "not-owned";
+	reason?: string;
+}
+
+export interface InstallRow {
+	scope: InstallScope;
+	from: string | null;
+	to: string | null;
+	loaded?: string | null;
+	status: "updated" | "unchanged" | "failed";
+	message?: string;
+	fix?: string;
+}
+
+export interface LocalCopy {
+	scope: "project" | "user";
+	name: string;
+	action: "removed" | "kept" | "created";
+	reason?: string;
+	/**
+	 * Set on a kept copy whose published files were already deleted when new
+	 * files turned up: it matches no commit, so no base is recorded for it.
+	 */
+	partial?: boolean;
+}
+
+export interface StepRecord {
+	id: StepId;
+	status: "done" | "skipped" | "failed";
+	detail?: string;
+}
+
+export interface MarketResult {
+	command: `market ${string}`;
+	outcome: MarketOutcome;
+	message: string;
+	planId?: string;
+	stale?: boolean;
+	marketplace?: string;
+	plugin?: string;
+	skill?: string;
+	version?: { from: string | null; to: string | null };
+	files?: Array<{ path: string; change: FileChange }>;
+	notPublished?: Array<{ path: string; reason: NotPublishedReason }>;
+	target?: DeliveryTarget;
+	commit?: string;
+	pullRequest?: string;
+	installs?: InstallRow[];
+	otherProjects?: number;
+	localCopy?: LocalCopy;
+	/** A plugin-wide publish settles one local copy per published skill. */
+	localCopies?: LocalCopy[];
+	marketplaces?: MarketplaceRow[];
+	/** `market list`: skills and plugins on this machine that no marketplace holds. */
+	local?: LocalItem[];
+	skills?: SkillStatusRow[];
+	plan?: string[];
+	steps: StepRecord[];
+	error?: { code: MarketErrorCode; message: string; fix?: string };
+}
+
+/**
+ * An expected failure of a market verb: a code the caller acts on, the words
+ * a user reads, and the next step. `exit` overrides the code's usual exit
+ * status (a usage error is exit 2 whatever its code).
+ */
+export class MarketError extends Error {
+	/** For `stale`: the marketplaces behind GitHub, when known. */
+	marketplaces?: readonly string[];
+	/**
+	 * True when the failing step had already changed something outside magus's
+	 * working clone (a pushed branch, a fork), so "nothing changed" is false.
+	 */
+	outsideWrite?: boolean;
+
+	constructor(
+		readonly code: MarketErrorCode,
+		message: string,
+		readonly fix?: string,
+		readonly exit?: number,
+	) {
+		super(message);
+		this.name = "MarketError";
+	}
+}
+
+/** A `stale` error naming the marketplaces whose copy here is behind GitHub. */
+export function staleError(
+	marketplaces: readonly string[],
+	message: string,
+	fix?: string,
+): MarketError {
+	const error = new MarketError("stale", message, fix);
+	error.marketplaces = marketplaces;
+	return error;
+}
+
+/** What a running step may hand back. */
+export interface StepOutcome {
+	/** A short note for the step's row. */
+	detail?: string;
+	/** Fields this step settles on the result: commit, pull request, installs… */
+	patch?: Partial<MarketResult>;
+	/** Stop here: later steps are skipped (a pull request moves no install). */
+	stop?: boolean;
+	/** The step was not needed and wrote nothing. */
+	skipped?: boolean;
+}
+
+export interface StepContext {
+	/** This project's root, where `.claude/skills` and project scope live. */
+	cwd: string;
+	/** The working clone the apply synced, when the plan works in one. */
+	clone: string | null;
+}
+
+export interface MarketStep {
+	id: StepId;
+	/** What the step does, in the user's words, for progress and results. */
+	label: string;
+	/** True when the step writes anywhere but magus's own working clone. */
+	outside: boolean;
+	run(ctx: StepContext): Promise<StepOutcome | undefined>;
+}
+
+/**
+ * A plan, ready for consent. Read-only to build; only {@link MarketStep.run}
+ * writes, and only inside an apply.
+ */
+export interface MarketPlan {
+	command: `market ${string}`;
+	/** One line per thing the apply will do, in plain words. */
+	lines: string[];
+	/** Hash of every material fact; consent binds to it. */
+	planId: string;
+	/** Fields the result carries from the plan (version, files, target…). */
+	summary: Partial<MarketResult>;
+	steps: MarketStep[];
+	/**
+	 * The marketplace whose working clone the apply locks and syncs before it
+	 * plans again. Null for a plan that needs no working clone.
+	 */
+	sync: { name: string; url: string } | null;
+	/** The marketplace to lock even without a sync (remove). */
+	lock: string | null;
+	/** Plan again from fresh state; the apply compares the new planId. */
+	replan(): Promise<PlanAnswer>;
+	/** The message of a finished apply. */
+	doneMessage: string;
+	/**
+	 * A second question a person must answer yes to (default no) before this
+	 * plan applies: a publish that replaces the plugin's version with --force.
+	 */
+	secondConfirm?: string;
+}
+
+/**
+ * What a planner answers: a plan to consent to, or a result that needs none
+ * (nothing to do), or an error.
+ */
+export type PlanAnswer =
+	| { kind: "plan"; plan: MarketPlan }
+	| { kind: "result"; result: MarketResult }
+	| {
+			kind: "error";
+			command: `market ${string}`;
+			error: MarketError;
+			stale?: boolean;
+	  };