magus-cli 7.12.2 → 7.14.0

package/src/services/market-ops-plugin.ts

@@ -0,0 +1,655 @@
+/**
+ * market-ops-plugin.ts — plans for `plugin create`, `plugin add` and
+ * `plugin delete`.
+ *
+ * Read-only planners. Each plan syncs magus's working clone in its apply and
+ * is planned again there before its first write.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { requireClaudeConfigDir } from "../utils/config-dir.js";
+import { displayPath } from "../utils/display-path.js";
+import { checkIgnore } from "./git-write.js";
+import { forgetBase, forgetBasesFor, recordBase } from "./market-bases.js";
+import {
+	type ChangeSpec,
+	changeSteps,
+	cloneOf,
+	deliveryTarget,
+	linkRefusal,
+	readJson,
+	targetLine,
+	writeJson,
+} from "./market-change.js";
+import { type Snapshot, cloneUrl } from "./market-clone.js";
+import {
+	copyFileUnder,
+	linkUnder,
+	refuseLinkUnder,
+	removeUnder,
+} from "./market-fs.js";
+import {
+	SYMLINK_MODE,
+	type SkillFile,
+	addPluginEntry,
+	currentVersion,
+	findSkillOwners,
+	inDomain,
+	joinRel,
+	nextVersion,
+	pluginEntries,
+	pluginRelDir,
+	pluginRootOf,
+	removePluginEntry,
+	setEntryVersion,
+	treeHash,
+	validPackageName,
+	validSkillName,
+} from "./market-layout.js";
+import {
+	type MarketCommand,
+	companyByName,
+	computePlanId,
+	freshSnapshot,
+	manifestAt,
+	planError,
+	resolvePluginRef,
+} from "./market-ops.js";
+import {
+	type InstalledAt,
+	installReaches,
+	installedScopes,
+	moveInstalls,
+	profileManaged,
+	readSourceSets,
+	removeLocalCopy,
+} from "./market-publish.js";
+import {
+	type TrustedRegistration,
+	listCompanyMarketplaces,
+} from "./market-registry.js";
+import {
+	type FileChange,
+	type LocalCopy,
+	MarketError,
+	type MarketPlan,
+	type MarketStep,
+	type PlanAnswer,
+} from "./market-types.js";
+import { fastForwardCloneIfPresent } from "./marketplace-refresh.js";
+import { getUserSkillsDir } from "./skills-manager.js";
+
+import {
+	MANIFEST,
+	type PluginView,
+	SCOPE_WORD,
+	bumpFrom,
+	bumpStep,
+	filesUnder,
+	installLines,
+	installStep,
+	readPlugin,
+	versionFiles,
+	versionLine,
+} from "./market-ops-content.js";
+
+// ─── plugin create ───────────────────────────────────────────────────────────
+
+/** The version a plugin new to a marketplace starts at. */
+export const NEW_PLUGIN_VERSION = "0.1.0";
+
+/** Where a new plugin goes in a marketplace snapshot. */
+export interface NewPluginLayout {
+	plugin: string;
+	/** The plugin's folder, repository-relative. */
+	dir: string;
+	pluginJsonPath: string;
+}
+
+/**
+ * Check `plugin` can be added to the marketplace as read, and name the
+ * folder it goes in: under `metadata.pluginRoot`, else `plugins/<name>`.
+ * Read-only.
+ */
+export function newPluginLayout(
+	m: TrustedRegistration,
+	snap: Snapshot,
+	manifest: Record<string, unknown>,
+	plugin: string,
+): NewPluginLayout {
+	if (!validPackageName(plugin)) {
+		throw new MarketError(
+			"invalid-name",
+			`${plugin} cannot be a plugin name (lower case letters, digits and dashes)`,
+		);
+	}
+	if (pluginEntries(manifest).some((p) => p.name === plugin)) {
+		throw new MarketError(
+			"name-taken",
+			`${m.name} already has a plugin named ${plugin}`,
+		);
+	}
+	const root = pluginRootOf(manifest);
+	const dir =
+		(typeof root === "string" ? pluginRelDir(plugin, root) : null) ??
+		joinRel("plugins", plugin);
+	if (filesUnder(snap, dir).length > 0) {
+		throw new MarketError(
+			"name-taken",
+			`${m.name} already has a folder ${dir}`,
+			"pick another plugin name",
+		);
+	}
+	return {
+		plugin,
+		dir,
+		pluginJsonPath: joinRel(dir, ".claude-plugin", "plugin.json"),
+	};
+}
+
+/**
+ * Write a new plugin's `plugin.json` and its marketplace entry into a
+ * working clone.
+ */
+export function writeNewPlugin(
+	clone: string,
+	m: TrustedRegistration,
+	manifest: Record<string, unknown>,
+	layout: NewPluginLayout,
+	description: string | undefined,
+): void {
+	const owner = (manifest.owner as { name?: unknown } | undefined)?.name;
+	const words = description ?? `${layout.plugin} plugin`;
+	writeJson(
+		clone,
+		layout.pluginJsonPath,
+		{
+			name: layout.plugin,
+			version: NEW_PLUGIN_VERSION,
+			description: words,
+			author: { name: typeof owner === "string" ? owner : m.name },
+		},
+		m.name,
+	);
+	const current = readJson(clone, MANIFEST, m.name);
+	writeJson(
+		clone,
+		MANIFEST,
+		addPluginEntry(current, {
+			name: layout.plugin,
+			source: `./${layout.dir}`,
+			description: words,
+			version: NEW_PLUGIN_VERSION,
+		}),
+		m.name,
+	);
+}
+
+export async function planPluginCreate(
+	ref: string,
+	description?: string,
+): Promise<PlanAnswer> {
+	const command: MarketCommand = "market plugin create";
+	try {
+		const { plugin, m } = await resolvePluginRef(ref);
+		if (!validPackageName(plugin)) {
+			throw new MarketError(
+				"invalid-name",
+				`${plugin} cannot be a plugin name (lower case letters, digits and dashes)`,
+			);
+		}
+		const snap = await freshSnapshot(m);
+		const manifest = await manifestAt(snap, m.name);
+		const layout = newPluginLayout(m, snap, manifest, plugin);
+		const { dir, pluginJsonPath } = layout;
+		const version = NEW_PLUGIN_VERSION;
+		const target = await deliveryTarget(m.source, m.name);
+		const files = [
+			{ path: MANIFEST, change: "modified" as const },
+			{ path: pluginJsonPath, change: "added" as const },
+		];
+		const state: ChangeSpec["state"] = {};
+		const steps: MarketStep[] = [
+			{
+				id: "edit",
+				label: `wrote ${plugin}`,
+				outside: false,
+				async run(ctx) {
+					writeNewPlugin(cloneOf(ctx), m, manifest, layout, description);
+					return undefined;
+				},
+			},
+			...changeSteps({
+				label: m.name,
+				source: m.source,
+				branch: snap.branch,
+				target,
+				stage: [MANIFEST, dir],
+				files,
+				message: `${plugin}: create plugin (${version})`,
+				slug: `${plugin}-create`,
+				prBody: `Creates the plugin \`${plugin}\` (${version}) in ${m.name}.`,
+				state,
+			}),
+			refreshStep(m.name, state),
+		];
+		const plan: MarketPlan = {
+			command,
+			lines: [
+				`Creates the plugin ${plugin} (${version}) in ${m.name}`,
+				targetLine(target, snap.branch),
+				"Installs nothing: install it from magus when you want it",
+			],
+			planId: computePlanId({
+				op: "plugin-create",
+				plugin,
+				marketplace: m.name,
+				commit: snap.commit,
+				description,
+				target,
+			}),
+			summary: {
+				marketplace: m.name,
+				plugin,
+				version: { from: null, to: version },
+				files,
+				target,
+			},
+			steps,
+			sync: { name: m.name, url: cloneUrl(m.source) },
+			lock: m.name,
+			replan: () => planPluginCreate(ref, description),
+			doneMessage: `${plugin}@${m.name} ${version} is in the marketplace.`,
+		};
+		return { kind: "plan", plan };
+	} catch (error) {
+		return planError(command, error);
+	}
+}
+
+/** After a push, bring Claude Code's clone forward so magus sees the change. */
+export function refreshStep(
+	name: string,
+	state: ChangeSpec["state"],
+): MarketStep {
+	return {
+		id: "refresh",
+		label: `brought Claude Code's copy of ${name} up to date`,
+		outside: true,
+		async run() {
+			if (!state.pushed) return { skipped: true };
+			const r = await fastForwardCloneIfPresent(name);
+			return r === "refreshed" ? undefined : { skipped: true, detail: r };
+		},
+	};
+}
+
+// ─── plugin add ──────────────────────────────────────────────────────────────
+
+export interface PluginAddArgs {
+	/** The plugin folder: absolute, or relative to the project. */
+	path: string;
+	/** The company marketplace; may be left out when there is one. */
+	to?: string;
+	/** The plugin's name there; its `plugin.json` name when left out. */
+	name?: string;
+}
+
+const PLUGIN_JSON = ".claude-plugin/plugin.json";
+
+/** The marketplace a `plugin add` goes to. */
+async function addTarget(to: string | undefined): Promise<TrustedRegistration> {
+	if (to) return companyByName(to);
+	const all = await listCompanyMarketplaces();
+	if (all.length === 1 && all[0]) return 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 one with --to <marketplace>",
+	);
+}
+
+/** The local plugin folder, checked: a real folder holding plugin.json. */
+function pluginFolder(
+	cwd: string,
+	given: string,
+): {
+	folder: string;
+	json: Record<string, unknown>;
+} {
+	const folder = path.resolve(cwd, given);
+	let stat: fs.Stats | null = null;
+	try {
+		stat = fs.lstatSync(folder);
+	} catch {
+		stat = null;
+	}
+	if (!stat) {
+		throw new MarketError("not-found", `There is no folder at ${given}`);
+	}
+	if (stat.isSymbolicLink() || !stat.isDirectory()) {
+		throw new MarketError(
+			"other",
+			`${given} is ${stat.isSymbolicLink() ? "a link to another folder" : "not a folder"}; magus adds only a plugin folder of its own`,
+		);
+	}
+	const installed = path.join(requireClaudeConfigDir(), "plugins");
+	if (folder === installed || folder.startsWith(`${installed}${path.sep}`)) {
+		throw new MarketError(
+			"other",
+			`${given} is a plugin Claude Code installed from a marketplace, not one of your own`,
+		);
+	}
+	const link = linkUnder(folder, PLUGIN_JSON);
+	if (link !== null) {
+		throw new MarketError(
+			"other",
+			`${given} reaches its plugin.json through a link at ${link}; magus copies only files of the folder's own`,
+		);
+	}
+	let json: unknown;
+	try {
+		json = JSON.parse(fs.readFileSync(path.join(folder, PLUGIN_JSON), "utf8"));
+	} catch (error) {
+		throw new MarketError(
+			(error as NodeJS.ErrnoException).code === "ENOENT"
+				? "not-found"
+				: "other",
+			(error as NodeJS.ErrnoException).code === "ENOENT"
+				? `${given} is not a plugin: it has no ${PLUGIN_JSON}`
+				: `${given}'s ${PLUGIN_JSON} is not valid JSON`,
+		);
+	}
+	if (!json || typeof json !== "object" || Array.isArray(json)) {
+		throw new MarketError(
+			"other",
+			`${given}'s ${PLUGIN_JSON} does not hold a JSON object`,
+		);
+	}
+	return { folder, json: json as Record<string, unknown> };
+}
+
+/**
+ * `market plugin add <path>`: copy a plugin folder of your own into a company
+ * marketplace as a new plugin, at its own version (0.1.0 when it has none).
+ * The folder stays where it is. Read-only.
+ */
+export async function planPluginAdd(
+	args: PluginAddArgs,
+	cwd: string,
+): Promise<PlanAnswer> {
+	const command: MarketCommand = "market plugin add";
+	try {
+		const { folder, json } = pluginFolder(cwd, args.path);
+		const own = typeof json.name === "string" ? json.name : undefined;
+		const plugin = args.name ?? own ?? path.basename(folder);
+		if (!validPackageName(plugin)) {
+			throw new MarketError(
+				"invalid-name",
+				`${plugin} cannot be a plugin name (lower case letters, digits and dashes)`,
+				"pass --name <name>",
+			);
+		}
+		const m = await addTarget(args.to);
+		const snap = await freshSnapshot(m);
+		const manifest = await manifestAt(snap, m.name);
+		const layout = newPluginLayout(m, snap, manifest, plugin);
+		const { dir, pluginJsonPath } = layout;
+		const theirVersion =
+			typeof json.version === "string" && nextVersion(json.version) !== null
+				? json.version
+				: null;
+		const version = theirVersion ?? NEW_PLUGIN_VERSION;
+		const sets = await readSourceSets(folder, snap.dir, dir, ".claude-plugin");
+		if (!sets.published.some((f) => f.path === PLUGIN_JSON)) {
+			throw new MarketError(
+				"other",
+				`${plugin}'s ${PLUGIN_JSON} would not be copied (${sets.notPublished.find((n) => n.path === PLUGIN_JSON)?.reason ?? "excluded"})`,
+			);
+		}
+		// plugin.json is written rather than copied when the marketplace needs
+		// a different name or a version it did not carry.
+		const rewrite = own !== plugin || theirVersion === null;
+		const description =
+			typeof json.description === "string" ? json.description : undefined;
+		const target = await deliveryTarget(m.source, m.name);
+		const files = [
+			{ path: MANIFEST, change: "modified" as const },
+			...sets.published.map((f) => ({
+				path: joinRel(dir, f.path),
+				change: "added" as const,
+			})),
+		];
+		const state: ChangeSpec["state"] = {};
+		const steps: MarketStep[] = [
+			{
+				id: "copy",
+				label: `copied ${plugin} into ${m.name}`,
+				outside: false,
+				async run(ctx) {
+					const clone = cloneOf(ctx);
+					const linked = linkRefusal(m.name);
+					for (const f of sets.published) {
+						refuseLinkUnder(clone, joinRel(dir, f.path), linked);
+					}
+					for (const f of sets.published) {
+						copyFileUnder(
+							clone,
+							joinRel(dir, f.path),
+							path.join(folder, f.path),
+							linked,
+						);
+					}
+					if (rewrite) {
+						writeJson(
+							clone,
+							pluginJsonPath,
+							{ ...json, name: plugin, version },
+							m.name,
+						);
+					}
+					const current = readJson(clone, MANIFEST, m.name);
+					writeJson(
+						clone,
+						MANIFEST,
+						addPluginEntry(current, {
+							name: plugin,
+							source: `./${dir}`,
+							...(description ? { description } : {}),
+							version,
+						}),
+						m.name,
+					);
+					return undefined;
+				},
+			},
+			...changeSteps({
+				label: m.name,
+				source: m.source,
+				branch: snap.branch,
+				target,
+				stage: [MANIFEST, dir],
+				files,
+				message: `${plugin}: add plugin (${version})`,
+				slug: `${plugin}-add`,
+				prBody: `Adds the plugin \`${plugin}\` (${version}) to ${m.name}.`,
+				...(rewrite ? {} : { verify: [{ dir, files: sets.published }] }),
+				state,
+			}),
+			refreshStep(m.name, state),
+		];
+		const lines = [
+			`Adds the plugin ${plugin} (${version}) from ${displayPath(folder, cwd)} to ${m.name}, in ${dir}`,
+			`Copies ${sets.published.length} file${sets.published.length === 1 ? "" : "s"}: ${sets.published.map((f) => f.path).join(", ")}`,
+			...(sets.untrackedFolder
+				? [
+						"This folder is not tracked in the project's git; every file is listed",
+					]
+				: []),
+			...(sets.notPublished.length > 0
+				? [
+						`Not copied: ${sets.notPublished.map((n) => `${n.path} (${n.reason})`).join(", ")}`,
+					]
+				: []),
+			...(rewrite
+				? [
+						`Writes its plugin.json with the name ${plugin} and the version ${version}`,
+					]
+				: []),
+			targetLine(target, snap.branch),
+			`Keeps that folder: install ${plugin}@${m.name} in magus to use the marketplace's copy, then remove the folder so it does not load twice`,
+		];
+		const plan: MarketPlan = {
+			command,
+			lines,
+			planId: computePlanId({
+				op: "plugin-add",
+				folder,
+				plugin,
+				marketplace: m.name,
+				commit: snap.commit,
+				hash: sets.hash,
+				notPublished: sets.notPublished,
+				version,
+				rewrite,
+				target,
+			}),
+			summary: {
+				marketplace: m.name,
+				plugin,
+				version: { from: null, to: version },
+				files,
+				notPublished: sets.notPublished,
+				target,
+			},
+			steps,
+			sync: { name: m.name, url: cloneUrl(m.source) },
+			lock: m.name,
+			replan: () => planPluginAdd({ ...args, to: m.name }, cwd),
+			doneMessage: `${plugin}@${m.name} ${version} is in the marketplace. Install it in magus to use it from there.`,
+		};
+		return { kind: "plan", plan };
+	} catch (error) {
+		return planError(command, error);
+	}
+}
+
+// ─── plugin delete ───────────────────────────────────────────────────────────
+
+export async function planPluginDelete(
+	ref: string,
+	cwd: string,
+): Promise<PlanAnswer> {
+	const command: MarketCommand = "market plugin delete";
+	try {
+		const view = await readPlugin(ref);
+		const { m, snap, plugin, dir } = view;
+		// Deleting a plugin removes its folder. A plugin at the marketplace's
+		// root, or one whose folder holds or sits inside another plugin's, has
+		// no folder of its own to remove.
+		const others = pluginEntries(view.manifest)
+			.filter((p) => p.name !== plugin)
+			.map((p) => ({
+				name: p.name,
+				dir: pluginRelDir(p.source, pluginRootOf(view.manifest)),
+			}));
+		const overlap = others.find(
+			(o) =>
+				o.dir !== null &&
+				(o.dir === dir ||
+					o.dir === "" ||
+					o.dir.startsWith(`${dir}/`) ||
+					dir.startsWith(`${o.dir}/`)),
+		);
+		if (dir === "" || overlap) {
+			throw new MarketError(
+				"other",
+				dir === ""
+					? `${plugin} is the root of ${m.name}, so deleting its folder would delete the whole marketplace — nothing changed`
+					: `${plugin} shares its folder with ${overlap?.name} in ${m.name}, so deleting it would delete that plugin too — nothing changed`,
+				"remove its entry from the marketplace by hand, or move the plugin into a folder of its own first",
+			);
+		}
+		const under = filesUnder(snap, dir);
+		const files = [
+			{ path: MANIFEST, change: "modified" as const },
+			...under.map((f) => ({
+				path: joinRel(dir, f.path),
+				change: "deleted" as const,
+			})),
+		];
+		const installs = await installedScopes(`${plugin}@${m.name}`, cwd);
+		const target = await deliveryTarget(m.source, m.name);
+		const state: ChangeSpec["state"] = {};
+		const steps: MarketStep[] = [
+			{
+				id: "edit",
+				label: `deleted ${plugin}`,
+				outside: false,
+				async run(ctx) {
+					const clone = cloneOf(ctx);
+					removeUnder(clone, dir, linkRefusal(m.name));
+					const current = readJson(clone, MANIFEST, m.name);
+					writeJson(
+						clone,
+						MANIFEST,
+						removePluginEntry(current, plugin),
+						m.name,
+					);
+					return undefined;
+				},
+			},
+			...changeSteps({
+				label: m.name,
+				source: m.source,
+				branch: snap.branch,
+				target,
+				stage: [MANIFEST, dir],
+				files,
+				message: `${plugin}: delete plugin`,
+				slug: `${plugin}-delete`,
+				prBody: `Deletes the plugin \`${plugin}\` from ${m.name}.`,
+				state,
+			}),
+			refreshStep(m.name, state),
+		];
+		const lines = [
+			`Deletes the plugin ${plugin} from ${m.name}: ${under.length} file${under.length === 1 ? "" : "s"}`,
+			targetLine(target, snap.branch),
+			...(installs.length > 0
+				? [
+						`Still installed here at ${installs.map((i) => `${SCOPE_WORD[i.scope]} ${i.version}`).join(", ")} — it keeps loading until it is uninstalled in magus`,
+					]
+				: []),
+		];
+		const plan: MarketPlan = {
+			command,
+			lines,
+			planId: computePlanId({
+				op: "plugin-delete",
+				plugin,
+				marketplace: m.name,
+				commit: snap.commit,
+				target,
+				installs,
+			}),
+			summary: { marketplace: m.name, plugin, files, target },
+			steps,
+			sync: { name: m.name, url: cloneUrl(m.source) },
+			lock: m.name,
+			replan: () => planPluginDelete(ref, cwd),
+			doneMessage: `${plugin} is no longer in ${m.name}.`,
+		};
+		return { kind: "plan", plan };
+	} catch (error) {
+		return planError(command, error);
+	}
+}