magus-cli 7.12.2 → 7.14.0

package/src/services/market-clone.ts

@@ -0,0 +1,572 @@
+/**
+ * market-clone.ts — magus's own working clone of a company marketplace, and
+ * the read-only view of a marketplace that every plan starts from.
+ *
+ * The working clone lives at `<claude config dir>/magus-market/<name>/`. It is
+ * not Claude Code's clone (a local commit would make that one dirty, and
+ * Claude Code deletes it on refresh) and it is disposable: every apply and
+ * every `market fetch` starts with fetch + `reset --hard` + `clean -ffdx`, and
+ * every apply ends with `reset --hard` + `clean -ffdx`.
+ *
+ * Plans never touch it. {@link readRemoteState} asks the remote for its head
+ * with `ls-remote` and reads whichever local copy already sits at that commit,
+ * through git's object store only.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { requireClaudeConfigDir } from "../utils/config-dir.js";
+import {
+	type GitFailure,
+	type GitResult,
+	type TreeEntry,
+	catFile,
+	cleanAll,
+	cloneFull,
+	fetch as gitFetch,
+	lsRemoteHead,
+	lsTree,
+	pushRef,
+	remoteUrl,
+	resetToRemote,
+	revParse,
+} from "./git-write.js";
+import {
+	forkParent,
+	ghAvailable,
+	prCreate,
+	repoFork,
+	repoForkAllowed,
+	viewerLogin,
+} from "./github-cli.js";
+import { type TrustedRegistration, isGithubSource } from "./market-registry.js";
+import { type DeliveryTarget, MarketError } from "./market-types.js";
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+/** `<claude config dir>/magus-market`: magus's own files for `magus market`. */
+export function marketRoot(): string {
+	return path.join(requireClaudeConfigDir(), "magus-market");
+}
+
+/** The working clone of marketplace `name`. */
+export function workingClonePath(name: string): string {
+	return path.join(marketRoot(), name);
+}
+
+/** The URL git clones and pushes for a normalised source. */
+export function cloneUrl(source: string): string {
+	return isGithubSource(source) ? `https://github.com/${source}.git` : source;
+}
+
+// ─── Git failures as market errors ───────────────────────────────────────────
+
+const SIGN_IN_FIX = "run `gh auth login`, then `gh auth setup-git`";
+
+/** A git failure in the terms of a market verb (the table in the CLI docs). */
+export function gitError(
+	r: { failure: GitFailure; message: string },
+	what: string,
+): MarketError {
+	switch (r.failure) {
+		case "no-network":
+			return new MarketError("no-network", `Could not reach ${what}`);
+		case "auth":
+			return new MarketError(
+				"gh-auth",
+				`Not signed in to GitHub for ${what}`,
+				SIGN_IN_FIX,
+			);
+		case "denied":
+			return new MarketError(
+				"no-access",
+				`Your account cannot write to ${what}`,
+				"ask the owner for write access, or install gh and sign in so magus can open a pull request",
+			);
+		case "rejected-non-ff":
+			return new MarketError(
+				"plan-changed",
+				`${what} changed on GitHub while this ran — nothing was pushed`,
+				"run the command again to see the new plan",
+			);
+		case "rejected-protected":
+			return new MarketError(
+				"other",
+				`${what} only takes changes through pull requests`,
+			);
+		case "timeout":
+			return new MarketError("timeout", `git did not finish in time (${what})`);
+		case "signing-timeout":
+			return new MarketError(
+				"signing-timeout",
+				"commit signing did not finish — approve it and run again",
+			);
+		default:
+			return new MarketError("other", r.message);
+	}
+}
+
+function must<T>(r: GitResult<T>, what: string): T {
+	if (!r.ok) throw gitError(r, what);
+	return r.value;
+}
+
+// ─── Lock ────────────────────────────────────────────────────────────────────
+
+const LOCK_ATTEMPTS = 20;
+const LOCK_RETRY_MS = 50;
+const EMPTY_LOCK_STALE_MS = 10_000;
+
+function alive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function removeIfPresent(file: string): void {
+	try {
+		fs.unlinkSync(file);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+/**
+ * Take the lock for marketplace `name`. Same scheme as the dependency
+ * installer's: the pid is written to a file of our own and the lock is a hard
+ * link to it, so the lock never exists without its holder's pid. A live holder
+ * refuses with `locked`; a dead one's lock is taken over. Returns the release.
+ */
+export async function acquireMarketLock(name: string): Promise<() => void> {
+	const lock = path.join(marketRoot(), `${name}.lock`);
+	fs.mkdirSync(path.dirname(lock), { recursive: true });
+	const mine = String(process.pid);
+	const staged = `${lock}.${mine}`;
+	fs.writeFileSync(staged, mine, { mode: 0o600 });
+	const busy = (pid: number | null) =>
+		new MarketError(
+			"locked",
+			`Another magus market command is working on ${name}${pid ? ` (pid ${pid})` : ""}`,
+			"wait for it to finish, then run this again",
+		);
+	try {
+		for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+			try {
+				fs.linkSync(staged, lock);
+				return () => {
+					try {
+						if (fs.readFileSync(lock, "utf8").trim() === mine) {
+							fs.unlinkSync(lock);
+						}
+					} catch {
+						// Already released.
+					}
+				};
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+			let stat: fs.Stats;
+			let text: string;
+			try {
+				stat = fs.lstatSync(lock);
+				text = stat.isFile() ? fs.readFileSync(lock, "utf8").trim() : "";
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+				throw error;
+			}
+			if (!stat.isFile()) {
+				removeIfPresent(lock);
+				continue;
+			}
+			const pid = Number.parseInt(text, 10);
+			if (Number.isInteger(pid) && pid > 0) {
+				if (alive(pid)) throw busy(pid);
+				removeIfPresent(lock);
+				continue;
+			}
+			if (Date.now() - stat.mtimeMs > EMPTY_LOCK_STALE_MS) {
+				removeIfPresent(lock);
+				continue;
+			}
+			await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+		}
+		throw busy(null);
+	} finally {
+		fs.rmSync(staged, { force: true });
+	}
+}
+
+// ─── Syncing the working clone ───────────────────────────────────────────────
+
+export interface SyncedClone {
+	dir: string;
+	/** The default branch; null for an empty repository. */
+	branch: string | null;
+	/** The default branch's commit; null for an empty repository. */
+	commit: string | null;
+}
+
+/**
+ * Bring the working clone of `name` to the remote's default branch: clone it
+ * when absent (or when it points elsewhere), else fetch; then `reset --hard`
+ * and `clean -ffdx`. Writes only the working clone.
+ */
+export async function syncWorkingClone(
+	name: string,
+	url: string,
+	label = name,
+): Promise<SyncedClone> {
+	const dir = workingClonePath(name);
+	const head = must(await lsRemoteHead(url), label);
+	let fresh = !fs.existsSync(path.join(dir, ".git"));
+	if (!fresh) {
+		const current = await remoteUrl(dir);
+		if (!current.ok || current.value !== url) fresh = true;
+	}
+	if (fresh) {
+		fs.rmSync(dir, { recursive: true, force: true });
+		fs.mkdirSync(path.dirname(dir), { recursive: true });
+		must(await cloneFull(url, dir), label);
+	} else {
+		must(await gitFetch(dir), label);
+	}
+	if (head.branch && head.commit) {
+		must(await resetToRemote(dir, head.branch), label);
+	}
+	must(await cleanAll(dir), label);
+	return { dir, branch: head.branch, commit: head.commit };
+}
+
+/** Return the working clone to the remote branch, untracked files removed. */
+export async function resetWorkingClone(
+	dir: string,
+	branch: string | null,
+): Promise<void> {
+	if (!fs.existsSync(path.join(dir, ".git"))) return;
+	if (branch) await resetToRemote(dir, branch);
+	await cleanAll(dir);
+}
+
+// ─── Read-only snapshots ─────────────────────────────────────────────────────
+
+/** A marketplace at one commit, read through git's object store. */
+export interface Snapshot {
+	/** The local repository the objects come from. */
+	dir: string;
+	commit: string;
+	branch: string;
+	/** Every blob (and link) at the commit, by repository path. */
+	entries: ReadonlyMap<string, TreeEntry>;
+	/** A file's text, or null when the commit has no such file. */
+	readText(file: string): Promise<string | null>;
+	/** A JSON file, parsed; null when absent. Throws on a file that does not parse. */
+	readJson(file: string): Promise<unknown>;
+}
+
+/** Read `commit` from the local repository `dir`. */
+export async function snapshotAt(
+	dir: string,
+	commit: string,
+	branch: string,
+	label: string,
+): Promise<Snapshot> {
+	const tree = must(await lsTree(dir, commit), label);
+	const entries = new Map(tree.map((e) => [e.path, e]));
+	const readText = async (file: string): Promise<string | null> => {
+		const entry = entries.get(file);
+		if (!entry) return null;
+		return must(await catFile(dir, entry.oid), label);
+	};
+	return {
+		dir,
+		commit,
+		branch,
+		entries,
+		readText,
+		async readJson(file) {
+			const text = await readText(file);
+			if (text === null) return null;
+			try {
+				return JSON.parse(text) as unknown;
+			} catch {
+				throw new MarketError(
+					"other",
+					`${label} holds a ${path.posix.basename(file)} that is not valid JSON (${file})`,
+				);
+			}
+		},
+	};
+}
+
+export type RemoteState =
+	| { fresh: true; snapshot: Snapshot }
+	| {
+			fresh: false;
+			/** Why the state is not current, in the user's words. */
+			reason: string;
+			fix: string;
+			/** The newest local copy, for display only. */
+			snapshot: Snapshot | null;
+			/** The failure behind an unreachable remote, when there was one. */
+			failure?: GitFailure;
+	  };
+
+async function headOf(dir: string): Promise<string | null> {
+	if (!fs.existsSync(path.join(dir, ".git")) && !isBareRepo(dir)) return null;
+	const r = await revParse(dir, "HEAD");
+	return r.ok ? r.value : null;
+}
+
+function isBareRepo(dir: string): boolean {
+	return (
+		fs.existsSync(path.join(dir, "HEAD")) &&
+		fs.existsSync(path.join(dir, "objects"))
+	);
+}
+
+/**
+ * The marketplace as GitHub has it now, without writing anything.
+ *
+ * `ls-remote` gives the default branch and its head. The first local copy at
+ * that head — magus's working clone, then Claude Code's — is read: fresh.
+ * When none is, or the remote cannot be reached, the state is stale and a
+ * write verb decides nothing from it.
+ */
+export async function readRemoteState(
+	m: TrustedRegistration,
+): Promise<RemoteState> {
+	const candidates = [workingClonePath(m.name), m.location].filter(
+		(d): d is string => !!d,
+	);
+	const newest = async (): Promise<Snapshot | null> => {
+		for (const dir of candidates) {
+			const head = await headOf(dir);
+			if (head) {
+				try {
+					return await snapshotAt(dir, head, "", m.name);
+				} catch {
+					// Unreadable: try the next copy.
+				}
+			}
+		}
+		return null;
+	};
+	const remote = await lsRemoteHead(cloneUrl(m.source));
+	if (!remote.ok) {
+		const auth = remote.failure === "auth";
+		return {
+			fresh: false,
+			reason: auth
+				? `this machine has no GitHub sign-in git can use for ${m.name}`
+				: `could not reach ${m.name}'s repository`,
+			fix: auth
+				? "run `gh auth setup-git`"
+				: "check the connection, then run `magus market fetch`",
+			snapshot: await newest(),
+			failure: remote.failure,
+		};
+	}
+	const { branch, commit } = remote.value;
+	if (!branch || !commit) {
+		return {
+			fresh: false,
+			reason: `${m.name}'s repository is empty`,
+			fix: `run \`magus market connect ${m.source}\` to set it up`,
+			snapshot: null,
+		};
+	}
+	for (const dir of candidates) {
+		if ((await headOf(dir)) === commit) {
+			return {
+				fresh: true,
+				snapshot: await snapshotAt(dir, commit, branch, m.name),
+			};
+		}
+	}
+	return {
+		fresh: false,
+		reason: "GitHub has newer commits this machine has not fetched",
+		fix: "run `magus market fetch`",
+		snapshot: await newest(),
+	};
+}
+
+// ─── Delivering a commit ─────────────────────────────────────────────────────
+
+export interface DeliverInput {
+	clone: string;
+	/** The default branch the change goes to. */
+	branch: string;
+	/** The marketplace's normalised source. */
+	source: string;
+	target: DeliveryTarget;
+	/** Names the pull-request branch, e.g. `review-kit-0.3.2`. */
+	slug: string;
+	title: string;
+	body: string;
+	label: string;
+}
+
+export type Delivery =
+	| { kind: "pushed" }
+	| { kind: "pull-request"; url: string; branch: string };
+
+async function openPullRequest(
+	input: DeliverInput,
+	remote: string,
+	headPrefix: string,
+): Promise<Delivery> {
+	const branch = `magus/${input.slug}-${Date.now().toString(36)}`;
+	must(await pushRef(input.clone, remote, "HEAD", branch), input.label);
+	const bodyDir = fs.mkdtempSync(path.join(os.tmpdir(), "magus-pr-"));
+	const bodyFile = path.join(bodyDir, "body.md");
+	try {
+		fs.writeFileSync(bodyFile, input.body);
+		const pr = await prCreate({
+			repo: input.source,
+			head: `${headPrefix}${branch}`,
+			base: input.branch,
+			title: input.title,
+			bodyFile,
+		});
+		if (!pr.ok) {
+			const error = new MarketError(
+				pr.failure === "gh-auth" ? "gh-auth" : "other",
+				`The change is on branch ${branch}, but the pull request could not be opened: ${pr.message}`,
+				pr.failure === "gh-auth" ? SIGN_IN_FIX : undefined,
+			);
+			error.outsideWrite = true;
+			throw error;
+		}
+		return { kind: "pull-request", url: pr.value, branch };
+	} finally {
+		fs.rmSync(bodyDir, { recursive: true, force: true });
+	}
+}
+
+async function viaFork(input: DeliverInput): Promise<Delivery> {
+	if (!isGithubSource(input.source) || !(await ghAvailable())) {
+		throw new MarketError(
+			"no-access",
+			`Your account cannot write to ${input.label}`,
+			"ask the owner for write access, or install gh and sign in so magus can open a pull request",
+		);
+	}
+	const allowed = await repoForkAllowed(input.source);
+	if (!allowed.ok || !allowed.value) {
+		throw new MarketError(
+			"fork-not-allowed",
+			`${input.label} does not allow forks`,
+			"ask its owner for write access",
+		);
+	}
+	const login = await viewerLogin();
+	if (!login.ok) {
+		throw new MarketError("gh-auth", "Not signed in to GitHub", SIGN_IN_FIX);
+	}
+	const fork = await repoFork(input.source);
+	if (!fork.ok) {
+		throw new MarketError(
+			"other",
+			`Could not fork ${input.source}: ${fork.message}`,
+		);
+	}
+	// The fork now exists on GitHub: whatever fails after this has changed
+	// something outside the working clone.
+	try {
+		return await fromFork(input, fork.value, login.value);
+	} catch (error) {
+		if (error instanceof MarketError) error.outsideWrite = true;
+		throw error;
+	}
+}
+
+async function fromFork(
+	input: DeliverInput,
+	forkName: string,
+	login: string,
+): Promise<Delivery> {
+	// Push only to a repository GitHub itself names as this account's fork of
+	// the source: a guessed name can be an unrelated, even public, repository.
+	const [owner] = forkName.split("/");
+	const parent = await forkParent(forkName);
+	if (
+		!parent.ok ||
+		parent.value === null ||
+		parent.value.toLowerCase() !== input.source.toLowerCase() ||
+		owner?.toLowerCase() !== login.toLowerCase()
+	) {
+		throw new MarketError(
+			"other",
+			`GitHub did not confirm ${forkName} as your fork of ${input.source} — nothing was pushed`,
+			"check your forks on GitHub, then run the command again",
+		);
+	}
+	const forkUrl = cloneUrl(forkName);
+	await waitForFork(forkUrl, forkName);
+	return openPullRequest(input, forkUrl, `${owner}:`);
+}
+
+const FORK_WAIT_TRIES = 10;
+const FORK_WAIT_MS = 3_000;
+
+/** GitHub creates a fork in the background: wait, bounded, until it answers. */
+async function waitForFork(url: string, name: string): Promise<void> {
+	for (let i = 0; i < FORK_WAIT_TRIES; i++) {
+		const head = await lsRemoteHead(url);
+		if (head.ok && head.value.commit !== null) return;
+		// A fork that is not there yet answers "Repository not found" (read as
+		// `denied`), so that one is waited out. Missing credentials will not
+		// become ready by waiting.
+		if (!head.ok && head.failure === "auth") {
+			throw new MarketError(
+				"gh-auth",
+				`git cannot read your fork ${name} — nothing was pushed`,
+				SIGN_IN_FIX,
+			);
+		}
+		await new Promise((r) => setTimeout(r, FORK_WAIT_MS));
+	}
+	throw new MarketError(
+		"other",
+		`Your fork ${name} is not ready on GitHub yet — nothing was pushed`,
+		"run the command again in a minute",
+	);
+}
+
+/**
+ * Deliver the working clone's HEAD commit: push it to the default branch, or,
+ * when that branch is protected, push a `magus/…` branch and open a pull
+ * request; with no write access and target `fork-pr`, fork and open the pull
+ * request from the fork. A non-fast-forward rejection is `plan-changed`:
+ * nothing is pushed in its place.
+ */
+export async function deliver(input: DeliverInput): Promise<Delivery> {
+	if (input.target === "fork-pr") return viaFork(input);
+	const pushed = await pushRef(input.clone, "origin", "HEAD", input.branch);
+	if (pushed.ok) return { kind: "pushed" };
+	if (pushed.failure === "rejected-protected") {
+		if (!isGithubSource(input.source) || !(await ghAvailable())) {
+			throw new MarketError(
+				"gh-missing",
+				`${input.label} only takes changes through pull requests, and gh is needed to open one`,
+				"install gh and run `gh auth login`",
+			);
+		}
+		return openPullRequest(input, "origin", "");
+	}
+	// The plan promised a push or a pull request on the source, never a fork
+	// the user did not agree to: a denied push stops here.
+	if (pushed.failure === "denied") {
+		throw new MarketError(
+			"no-access",
+			`Your account cannot write to ${input.label} — nothing was pushed`,
+			"ask its owner for write access",
+		);
+	}
+	throw gitError(pushed, input.label);
+}

package/src/services/market-fs.ts

@@ -0,0 +1,138 @@
+/**
+ * market-fs.ts — file writes that stay where they were aimed.
+ *
+ * A marketplace repository can commit symbolic links, and a working clone
+ * checks them out as links. A write joined under such a path would follow
+ * the link and land outside the clone or the skill folder, where no later
+ * reset or verification can undo it. Every write the market verbs make into
+ * a clone or a local skill folder first checks that no existing part of the
+ * path below its root is a link.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The first existing part of `rel` under `root` that is a symbolic link, as a
+ * `/`-joined relative path, or null when there is none. `root` itself is
+ * trusted. Parts that do not exist yet end the walk: nothing below them can
+ * be a link.
+ */
+export function linkUnder(root: string, rel: string): string | null {
+	const parts = rel.split("/").filter((p) => p !== "" && p !== ".");
+	let at = root;
+	for (let i = 0; i < parts.length; i++) {
+		at = path.join(at, parts[i] as string);
+		let stat: fs.Stats;
+		try {
+			stat = fs.lstatSync(at);
+		} catch {
+			return null;
+		}
+		if (stat.isSymbolicLink()) return parts.slice(0, i + 1).join("/");
+	}
+	return null;
+}
+
+/** Throw `error(link)` when any existing part of `rel` under `root` is a link. */
+export function refuseLinkUnder(
+	root: string,
+	rel: string,
+	error: (link: string) => Error,
+): void {
+	const link = linkUnder(root, rel);
+	if (link !== null) throw error(link);
+}
+
+/**
+ * Write `data` to `file` as a new regular file, never through a link: what
+ * is at `file` now (a file or a link) is removed first, and the write fails
+ * rather than follow anything that appears in between.
+ */
+export function writeFileNoFollow(file: string, data: string): void {
+	fs.rmSync(file, { force: true });
+	fs.writeFileSync(file, data, { flag: "wx" });
+}
+
+/** How a refused write is reported: the link it would have gone through. */
+export type LinkError = (link: string) => Error;
+
+/**
+ * Make the folders of `rel` under `root`, after checking that no existing
+ * part of it is a link. Parts that do not exist are created as real folders.
+ */
+export function mkdirUnder(root: string, rel: string, error: LinkError): void {
+	refuseLinkUnder(root, rel, error);
+	fs.mkdirSync(path.join(root, rel), { recursive: true });
+}
+
+/**
+ * Write `data` to `rel` under `root` as a new regular file: every existing
+ * part of the path is checked for a link first, the folders are made, and
+ * the leaf is written without following anything (`writeFileNoFollow`).
+ */
+export function writeFileUnder(
+	root: string,
+	rel: string,
+	data: string,
+	error: LinkError,
+): void {
+	refuseLinkUnder(root, rel, error);
+	const out = path.join(root, rel);
+	fs.mkdirSync(path.dirname(out), { recursive: true });
+	refuseLinkUnder(root, rel, error);
+	writeFileNoFollow(out, data);
+}
+
+/** `writeFileUnder` for JSON, written the way marketplace files are. */
+export function writeJsonUnder(
+	root: string,
+	rel: string,
+	value: unknown,
+	error: LinkError,
+): void {
+	writeFileUnder(root, rel, `${JSON.stringify(value, null, 2)}\n`, error);
+}
+
+/** Read JSON from `rel` under `root`, refusing a path that passes a link. */
+export function readJsonUnder(
+	root: string,
+	rel: string,
+	error: LinkError,
+): Record<string, unknown> {
+	refuseLinkUnder(root, rel, error);
+	return JSON.parse(fs.readFileSync(path.join(root, rel), "utf8")) as Record<
+		string,
+		unknown
+	>;
+}
+
+/**
+ * Copy `from` to `rel` under `root` as a new regular file. Whatever is at
+ * the destination (a file or a link) is removed first and the copy is
+ * exclusive, so it never writes through a link.
+ */
+export function copyFileUnder(
+	root: string,
+	rel: string,
+	from: string,
+	error: LinkError,
+): void {
+	refuseLinkUnder(root, rel, error);
+	const out = path.join(root, rel);
+	fs.mkdirSync(path.dirname(out), { recursive: true });
+	refuseLinkUnder(root, rel, error);
+	fs.rmSync(out, { force: true });
+	fs.copyFileSync(from, out, fs.constants.COPYFILE_EXCL);
+}
+
+/**
+ * Remove `rel` under `root` (recursively for a folder). The folders above it
+ * must not be links, or the removal would land outside `root`; the leaf
+ * itself may be one, and then only the link is removed.
+ */
+export function removeUnder(root: string, rel: string, error: LinkError): void {
+	const parent = path.posix.dirname(rel);
+	if (parent !== "." && parent !== "") refuseLinkUnder(root, parent, error);
+	fs.rmSync(path.join(root, rel), { recursive: true, force: true });
+}