magus-cli 7.13.0 → 7.14.1

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

@@ -1,5 +1,6 @@
 /**
- * market-ops-plugin.ts — plans for `plugin create` and `plugin delete`.
+ * 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.
@@ -7,6 +8,8 @@
 
 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 {
@@ -20,7 +23,12 @@ import {
 	writeJson,
 } from "./market-change.js";
 import { type Snapshot, cloneUrl } from "./market-clone.js";
-import { removeUnder } from "./market-fs.js";
+import {
+	copyFileUnder,
+	linkUnder,
+	refuseLinkUnder,
+	removeUnder,
+} from "./market-fs.js";
 import {
 	SYMLINK_MODE,
 	type SkillFile,
@@ -41,6 +49,7 @@ import {
 } from "./market-layout.js";
 import {
 	type MarketCommand,
+	companyByName,
 	computePlanId,
 	freshSnapshot,
 	manifestAt,
@@ -87,6 +96,96 @@ import {
 
 // ─── 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,
@@ -102,26 +201,9 @@ export async function planPluginCreate(
 		}
 		const snap = await freshSnapshot(m);
 		const manifest = await manifestAt(snap, m.name);
-		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",
-			);
-		}
-		const owner = (manifest.owner as { name?: unknown } | undefined)?.name;
-		const pluginJsonPath = joinRel(dir, ".claude-plugin", "plugin.json");
-		const version = "0.1.0";
+		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 },
@@ -134,30 +216,7 @@ export async function planPluginCreate(
 				label: `wrote ${plugin}`,
 				outside: false,
 				async run(ctx) {
-					const clone = cloneOf(ctx);
-					writeJson(
-						clone,
-						pluginJsonPath,
-						{
-							name: plugin,
-							version,
-							description: description ?? `${plugin} plugin`,
-							author: { name: typeof owner === "string" ? owner : m.name },
-						},
-						m.name,
-					);
-					const current = readJson(clone, MANIFEST, m.name);
-					writeJson(
-						clone,
-						MANIFEST,
-						addPluginEntry(current, {
-							name: plugin,
-							source: `./${dir}`,
-							description: description ?? `${plugin} plugin`,
-							version,
-						}),
-						m.name,
-					);
+					writeNewPlugin(cloneOf(ctx), m, manifest, layout, description);
 					return undefined;
 				},
 			},
@@ -210,7 +269,10 @@ export async function planPluginCreate(
 }
 
 /** After a push, bring Claude Code's clone forward so magus sees the change. */
-function refreshStep(name: string, state: ChangeSpec["state"]): MarketStep {
+export function refreshStep(
+	name: string,
+	state: ChangeSpec["state"],
+): MarketStep {
 	return {
 		id: "refresh",
 		label: `brought Claude Code's copy of ${name} up to date`,
@@ -223,6 +285,263 @@ function refreshStep(name: string, state: ChangeSpec["state"]): MarketStep {
 	};
 }
 
+// ─── 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(