magus-cli 7.12.2 → 7.14.0

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

@@ -0,0 +1,1227 @@
+/**
+ * market-ops-publish.ts — `market status` and `market publish`: how a local
+ * copy of a company skill stands against its plugin, and sending its edits
+ * back as the plugin's next patch version.
+ *
+ * One compare serves both. Three trees, each restricted to the compare
+ * domain (no symlinks, dotfiles, `node_modules/`, or files either side
+ * ignores) before hashing:
+ * - `ours`: the files the copy would publish;
+ * - `theirs`: the plugin's skill at GitHub's current commit;
+ * - `base`: the skill at the commit the copy was made from, known only while
+ *   the folder holds the provenance token of its base record.
+ *
+ * Status is read-only. Publish plans read-only too; its apply replaces only
+ * the in-domain part of the plugin's skill, commits exactly the planned paths,
+ * delivers, moves this machine's installs through `claude plugin` commands,
+ * and removes the local copy only when it holds exactly the committed files.
+ * A plugin-wide publish does the same for every skill of one plugin edited
+ * here, as one commit and one version.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { checkIgnore, hashObject, lsTree } from "./git-write.js";
+import { readBase, recordBase } from "./market-bases.js";
+import {
+	type ChangeSpec,
+	changeSteps,
+	cloneOf,
+	deliveryTarget,
+	targetLine,
+} from "./market-change.js";
+import {
+	type RemoteState,
+	cloneUrl,
+	readRemoteState,
+	workingClonePath,
+} from "./market-clone.js";
+import { refuseLinkUnder } from "./market-fs.js";
+import {
+	type CompareState,
+	type SkillFile,
+	compareSkillTrees,
+	excludedByShape,
+	findSkillOwners,
+	inDomain,
+	joinRel,
+	pluginEntries,
+	pluginRelDir,
+	pluginRootOf,
+	treeHash,
+} from "./market-layout.js";
+import {
+	type PluginView,
+	bumpFrom,
+	bumpStep,
+	filesUnder,
+	installLines,
+	installStep,
+	pluginViewAt,
+	readPlugin,
+	versionFiles,
+	versionLine,
+} from "./market-ops-content.js";
+import {
+	PROFILE_KEEPS,
+	checkSkillName,
+	ownerOf,
+	skillFolder,
+} from "./market-ops-skill.js";
+import {
+	type MarketCommand,
+	computePlanId,
+	errorResult,
+	manifestAt,
+	planError,
+} from "./market-ops.js";
+import {
+	type InstalledAt,
+	type SourceSets,
+	copyMismatch,
+	installReaches,
+	installedScopes,
+	inventory,
+	offHereReason,
+	profileManaged,
+	readSourceSets,
+	settleLocalCopy,
+} from "./market-publish.js";
+import {
+	type TrustedRegistration,
+	listCompanyMarketplaces,
+} from "./market-registry.js";
+import {
+	type FileChange,
+	type LocalCopy,
+	MarketError,
+	type MarketPlan,
+	type MarketResult,
+	type MarketStep,
+	type PlanAnswer,
+	type SkillStatusRow,
+} from "./market-types.js";
+import { getUserSkillsDir } from "./skills-manager.js";
+
+type TreeFile = SkillFile & { mode: string };
+
+// ─── The compare ─────────────────────────────────────────────────────────────
+
+export interface LocalCompare {
+	state: CompareState;
+	/** The copy's inventory, published set and files not published. */
+	sets: SourceSets;
+	/** The plugin's skill now, inside the compare domain. */
+	theirsIn: TreeFile[];
+	/** The plugin's skill now, outside it: publish never touches these. */
+	theirsOut: TreeFile[];
+	/** The commit the copy was made from, when its record is usable. */
+	baseCommit: string | null;
+	/** Why there is no base, in the user's words. */
+	noBaseReason?: string;
+	/** What publishing changes in the plugin's skill, skill-relative. */
+	changes: Array<{ path: string; change: FileChange }>;
+}
+
+/** Which of `paths` (skill-relative) each side ignores. */
+async function ignoredBy(
+	folder: string,
+	folderIgnored: boolean,
+	repo: string,
+	skillDir: string,
+	paths: readonly string[],
+): Promise<{ here: Set<string>; there: Set<string> }> {
+	if (paths.length === 0) return { here: new Set(), there: new Set() };
+	// The source's own rules do not apply to a folder its repository ignores
+	// as a whole (magus ignores the skill folders a profile installs).
+	const here = folderIgnored ? null : await checkIgnore(folder, paths);
+	const there = await checkIgnore(
+		repo,
+		paths.map((p) => joinRel(skillDir, p)),
+	);
+	const prefix = `${skillDir}/`;
+	return {
+		here: here?.ok ? here.value : new Set(),
+		there: new Set(
+			[...(there.ok ? there.value : [])].map((p) =>
+				p.startsWith(prefix) ? p.slice(prefix.length) : p,
+			),
+		),
+	};
+}
+
+/** The skill's files at `commit`, from whichever local copy holds it. */
+async function treeAt(
+	view: PluginView,
+	commit: string,
+	skillDir: string,
+): Promise<TreeFile[] | null> {
+	const dirs = [
+		view.snap.dir,
+		workingClonePath(view.m.name),
+		view.m.location,
+	].filter((d, i, all): d is string => !!d && all.indexOf(d) === i);
+	const prefix = `${skillDir}/`;
+	for (const dir of dirs) {
+		if (!fs.existsSync(dir)) continue;
+		const r = await lsTree(dir, commit, skillDir);
+		if (r.ok) {
+			return r.value
+				.filter((e) => e.path.startsWith(prefix))
+				.map((e) => ({
+					path: e.path.slice(prefix.length),
+					oid: e.oid,
+					mode: e.mode,
+				}));
+		}
+	}
+	return null;
+}
+
+/**
+ * Compare the local copy at `folder` with `view`'s skill `skill`, from the
+ * fresh snapshot the view was read at. Read-only.
+ */
+export async function compareLocal(
+	folder: string,
+	view: PluginView,
+	skill: string,
+): Promise<LocalCompare> {
+	const skillDir = joinRel(view.dir, "skills", skill);
+	const sets = await readSourceSets(folder, view.snap.dir, skillDir);
+	const theirs = filesUnder(view.snap, skillDir);
+
+	const record = readBase(folder);
+	let base: TreeFile[] | null = null;
+	let noBaseReason: string | undefined;
+	if (!record) {
+		noBaseReason = "this copy has no record of which version it came from";
+	} else if (
+		record.marketplace !== view.m.name ||
+		record.plugin !== view.plugin ||
+		record.skill !== skill
+	) {
+		noBaseReason = `this copy was made from ${record.plugin}@${record.marketplace}, not ${view.plugin}@${view.m.name}`;
+	} else {
+		base = await treeAt(view, record.commit, skillDir);
+		if (!base) {
+			noBaseReason =
+				"the version this copy came from is not on this machine any more";
+		}
+	}
+
+	const paths = [...new Set([...theirs, ...(base ?? [])].map((f) => f.path))];
+	const ignored = await ignoredBy(
+		folder,
+		sets.untrackedFolder,
+		view.snap.dir,
+		skillDir,
+		paths,
+	);
+	const domain = (f: TreeFile) =>
+		inDomain(f.path, f.mode, ignored.here, ignored.there);
+	const theirsIn = theirs.filter(domain);
+	const theirsOut = theirs.filter((f) => !domain(f));
+	const state = compareSkillTrees(
+		base ? treeHash(base.filter(domain)) : null,
+		treeHash(theirsIn),
+		sets.hash,
+	);
+
+	const now = new Map(theirsIn.map((f) => [f.path, f.oid]));
+	const ours = new Set(sets.published.map((f) => f.path));
+	const changes: LocalCompare["changes"] = [];
+	for (const f of sets.published) {
+		const was = now.get(f.path);
+		if (was === undefined) changes.push({ path: f.path, change: "added" });
+		else if (was !== f.oid) changes.push({ path: f.path, change: "modified" });
+	}
+	for (const f of theirsIn) {
+		if (!ours.has(f.path)) changes.push({ path: f.path, change: "deleted" });
+	}
+	changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+
+	return {
+		state,
+		sets,
+		theirsIn,
+		theirsOut,
+		baseCommit: base && record ? record.commit : null,
+		...(noBaseReason ? { noBaseReason } : {}),
+		changes,
+	};
+}
+
+function changeList(changes: LocalCompare["changes"]): string {
+	return changes.map((c) => `${c.path} (${c.change})`).join(", ");
+}
+
+function plural(n: number, word: string): string {
+	return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+// ─── status ──────────────────────────────────────────────────────────────────
+
+export interface LocalFolder {
+	skill: string;
+	from: "project" | "user";
+	path: string;
+}
+
+/** Skill folders in this project and in the USER skills, real folders only. */
+export function localSkillFolders(cwd: string, only?: string): LocalFolder[] {
+	const out: LocalFolder[] = [];
+	const roots = [
+		{ from: "project" as const, dir: path.join(cwd, ".claude", "skills") },
+		{ from: "user" as const, dir: getUserSkillsDir() },
+	];
+	const seen = new Set<string>();
+	for (const { from, dir } of roots) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const d of entries) {
+			if (!d.isDirectory() || (only && d.name !== only)) continue;
+			const folder = path.join(dir, d.name);
+			if (seen.has(folder)) continue;
+			if (!fs.existsSync(path.join(folder, "SKILL.md"))) continue;
+			seen.add(folder);
+			out.push({ skill: d.name, from, path: folder });
+		}
+	}
+	return out.sort((a, b) =>
+		a.skill === b.skill
+			? a.from.localeCompare(b.from)
+			: a.skill.localeCompare(b.skill),
+	);
+}
+
+interface MarketRead {
+	m: TrustedRegistration;
+	state: RemoteState;
+	manifest: Record<string, unknown> | null;
+}
+
+async function readMarket(m: TrustedRegistration): Promise<MarketRead> {
+	const state = await readRemoteState(m);
+	let manifest: Record<string, unknown> | null = null;
+	if (state.snapshot) {
+		try {
+			manifest = await manifestAt(state.snapshot, m.name);
+		} catch {
+			manifest = null;
+		}
+	}
+	return { m, state, manifest };
+}
+
+function staleReason(r: MarketRead): string {
+	return r.state.fresh ? "" : `${r.m.name}: ${r.state.reason}`;
+}
+
+const ROW_STATE: Record<CompareState, SkillStatusRow["state"]> = {
+	fast: "edited",
+	same: "same",
+	"plugin-newer": "plugin-newer",
+	"no-base": "no-base",
+	conflict: "conflict",
+};
+
+/**
+ * `market status [<skill>]`: every skill folder here and in the USER skills
+ * that a company plugin holds, and how it stands. Read-only: no clone is
+ * created, fetched, reset or locked.
+ */
+export async function marketStatus(
+	skill: string | undefined,
+	cwd: string,
+): Promise<MarketResult> {
+	const command: MarketCommand = "market status";
+	try {
+		if (skill) checkSkillName(skill);
+		const folders = localSkillFolders(cwd, skill);
+		if (skill && folders.length === 0) {
+			throw new MarketError(
+				"not-found",
+				`Neither this project nor your USER skills have a skill named ${skill}`,
+			);
+		}
+		const reads = await Promise.all(
+			(await listCompanyMarketplaces()).map(readMarket),
+		);
+		const candidates = reads.flatMap((r) =>
+			r.state.snapshot && r.manifest
+				? [
+						{
+							marketplace: r.m.name,
+							plugins: pluginEntries(r.manifest).map((p) => ({
+								name: p.name,
+								dir: pluginRelDir(p.source, pluginRootOf(r.manifest)),
+							})),
+							paths: new Set(r.state.snapshot.entries.keys()),
+						},
+					]
+				: [],
+		);
+		const unread = reads.filter((r) => !r.state.snapshot || !r.manifest);
+
+		const rows: SkillStatusRow[] = [];
+		for (const f of folders) {
+			const row = {
+				skill: f.skill,
+				from: f.from,
+				path: f.path,
+				owner: null as string | null,
+			};
+			const owners = findSkillOwners(candidates, f.skill);
+			if (owners.length > 1) {
+				rows.push({ ...row, owners, state: "ambiguous" });
+				continue;
+			}
+			if (owners.length === 0) {
+				const record = readBase(f.path);
+				const from = record
+					? reads.find((r) => r.m.name === record.marketplace)
+					: undefined;
+				if (record && from && !from.state.fresh) {
+					rows.push({
+						...row,
+						owner: `${record.plugin}@${record.marketplace}`,
+						state: "not-checked",
+						reason: staleReason(from),
+					});
+				} else if (skill && unread.length > 0) {
+					rows.push({
+						...row,
+						state: "not-checked",
+						reason: unread.map(staleReason).join("; "),
+					});
+				} else if (skill) {
+					rows.push({ ...row, state: "not-owned" });
+				}
+				continue;
+			}
+			const owner = owners[0] as string;
+			const at = owner.lastIndexOf("@");
+			const read = reads.find((r) => r.m.name === owner.slice(at + 1));
+			if (!read?.state.fresh || !read.manifest) {
+				rows.push({
+					...row,
+					owner,
+					state: "not-checked",
+					reason: read ? staleReason(read) : "not read",
+				});
+				continue;
+			}
+			try {
+				const view = await pluginViewAt(
+					read.m,
+					read.state.snapshot,
+					read.manifest,
+					owner.slice(0, at),
+				);
+				const cmp = await compareLocal(f.path, view, f.skill);
+				rows.push({ ...row, owner, state: ROW_STATE[cmp.state] });
+			} catch (error) {
+				rows.push({
+					...row,
+					owner,
+					state: "not-checked",
+					reason: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		const stale = reads.some((r) => !r.state.fresh);
+		const edited = rows.filter((r) =>
+			["edited", "no-base", "conflict"].includes(r.state),
+		).length;
+		return {
+			command,
+			outcome: "ok",
+			message:
+				rows.length === 0
+					? "No local skill here belongs to a company plugin"
+					: edited === 0
+						? `${plural(rows.length, "local skill")} from company plugins; none has edits to publish`
+						: `${plural(rows.length, "local skill")} from company plugins; ${edited} with edits to publish`,
+			...(skill ? { skill } : {}),
+			...(stale ? { stale: true } : {}),
+			skills: rows,
+			steps: [],
+		};
+	} catch (error) {
+		return errorResult(command, error);
+	}
+}
+
+// ─── publish ─────────────────────────────────────────────────────────────────
+
+export interface PublishArgs {
+	skill: string;
+	/** `plugin@marketplace`; inferred from fresh state when left out. */
+	plugin?: string;
+	from: "project" | "global";
+	keepLocal: boolean;
+	force: boolean;
+}
+
+function whoseCopy(from: "project" | "global"): string {
+	return from === "global" ? "your USER copy" : "this project's copy";
+}
+
+/** The local copy to publish: a real folder holding SKILL.md. */
+function sourceFolder(cwd: string, args: PublishArgs): string {
+	checkSkillName(args.skill);
+	const folder = skillFolder(cwd, args.from, args.skill);
+	const where = args.from === "global" ? "Your USER skills" : "This project";
+	let stat: fs.Stats | null = null;
+	try {
+		stat = fs.lstatSync(folder);
+	} catch {
+		stat = null;
+	}
+	if (!stat || !fs.existsSync(path.join(folder, "SKILL.md"))) {
+		throw new MarketError(
+			"not-found",
+			`${where} ${args.from === "global" ? "have" : "has"} no skill named ${args.skill}`,
+			`to change a company skill, copy it here first with \`magus market skill edit ${args.skill}\``,
+		);
+	}
+	if (stat.isSymbolicLink()) {
+		throw new MarketError(
+			"other",
+			`${args.skill} here is a link to another folder; magus publishes only a folder of its own`,
+		);
+	}
+	return folder;
+}
+
+const FORCE_FIX =
+	"to replace the plugin's version with this copy, run again with --force";
+
+/**
+ * Why a publish keeps the local copy at `folder`, or null when it will be
+ * removed once the push lands and every install moves. Read-only.
+ */
+async function keepReasonFor(input: {
+	folder: string;
+	skill: string;
+	from: "project" | "global";
+	keepLocal: boolean;
+	plugin: string;
+	pluginId: string;
+	installs: readonly InstalledAt[];
+	committed: readonly SkillFile[];
+	cwd: string;
+}): Promise<{ reason: string | null; managed: boolean }> {
+	const managed =
+		input.from === "project" && (await profileManaged(input.cwd, input.skill));
+	const reason = input.keepLocal
+		? "--keep-local"
+		: managed
+			? PROFILE_KEEPS
+			: !installReaches(
+						input.from === "global" ? "user" : "project",
+						input.installs.map((i) => i.scope),
+					)
+				? `${input.plugin} is not installed where this copy loads`
+				: ((await offHereReason(input.plugin, input.pluginId, input.cwd)) ??
+					(await copyMismatch(
+						input.folder,
+						input.committed,
+						"will not be published",
+					)));
+	return { reason, managed };
+}
+
+export async function planPublish(
+	args: PublishArgs,
+	cwd: string,
+): Promise<PlanAnswer> {
+	const command: MarketCommand = "market publish";
+	try {
+		const folder = sourceFolder(cwd, args);
+		const view = await ownerOf(args.skill, args.plugin);
+		const { m, snap, plugin } = view;
+		const pluginId = `${plugin}@${m.name}`;
+		const skillDir = joinRel(view.dir, "skills", args.skill);
+		const cmp = await compareLocal(folder, view, args.skill);
+		const copyWord = whoseCopy(args.from);
+		const files = cmp.changes.map((c) => ({
+			path: joinRel(skillDir, c.path),
+			change: c.change,
+		}));
+		const base = {
+			marketplace: m.name,
+			plugin,
+			skill: args.skill,
+			...(cmp.sets.notPublished.length > 0
+				? { notPublished: cmp.sets.notPublished }
+				: {}),
+		};
+
+		if (cmp.state === "same") {
+			return {
+				kind: "result",
+				result: {
+					command,
+					outcome: "unchanged",
+					message: `${copyWord} of ${args.skill} is the same as ${pluginId}'s — nothing to publish`,
+					...base,
+					steps: [],
+				},
+			};
+		}
+		if (cmp.state === "plugin-newer") {
+			return {
+				kind: "result",
+				result: {
+					command,
+					outcome: "plugin-newer",
+					message: `${pluginId} has a newer version of ${args.skill}, and ${copyWord} has no edits — nothing to publish. Delete ${copyWord} to use the plugin's version`,
+					...base,
+					steps: [],
+				},
+			};
+		}
+		const forced = cmp.state === "no-base" || cmp.state === "conflict";
+		const compareLine =
+			cmp.state === "fast"
+				? `${capital(copyWord)} has edits, and ${pluginId} has not changed ${args.skill} since the copy was made`
+				: cmp.state === "no-base"
+					? `${capital(cmp.noBaseReason ?? "this copy has no record of which version it came from")}; publishing replaces the plugin's version. Next time, start an edit with \`magus market skill edit\``
+					: `${args.skill} changed both here and in ${pluginId} on GitHub since the copy was made; publishing replaces the plugin's version`;
+		const diffLine = `Your copy vs the plugin: ${changeList(cmp.changes)}`;
+		if (forced && !args.force) {
+			const message =
+				cmp.state === "no-base"
+					? `${capital(cmp.noBaseReason ?? "this copy has no record of which version it came from")} — nothing changed`
+					: `${args.skill} changed both here and in ${pluginId} on GitHub — nothing changed`;
+			return {
+				kind: "result",
+				result: {
+					command,
+					outcome: "failed",
+					message,
+					...base,
+					files,
+					plan: [compareLine, diffLine],
+					steps: [],
+					error: {
+						code: cmp.state === "no-base" ? "no-base" : "conflict",
+						message,
+						fix: FORCE_FIX,
+					},
+				},
+			};
+		}
+
+		const { from, to } = bumpFrom(view);
+		const target = await deliveryTarget(m.source, m.name);
+		const installs = await installedScopes(pluginId, cwd);
+		const copyScope = args.from === "global" ? "user" : "project";
+		const committed: SkillFile[] = [
+			...cmp.sets.published,
+			...cmp.theirsOut.map((f) => ({ path: f.path, oid: f.oid })),
+		];
+		const { reason: keepReason, managed } = await keepReasonFor({
+			folder,
+			skill: args.skill,
+			from: args.from,
+			keepLocal: args.keepLocal,
+			plugin,
+			pluginId,
+			installs,
+			committed,
+			cwd,
+		});
+		const predicted: LocalCopy = keepReason
+			? {
+					scope: copyScope,
+					name: args.skill,
+					action: "kept",
+					reason: keepReason,
+				}
+			: { scope: copyScope, name: args.skill, action: "removed" };
+
+		const state: ChangeSpec["state"] & { moved?: boolean } = {};
+		const steps: MarketStep[] = [
+			replaceStep(folder, skillDir, plugin, args.skill, cmp, committed),
+			bumpStep(view, to),
+			...changeSteps({
+				label: m.name,
+				source: m.source,
+				branch: snap.branch,
+				target,
+				stage: [skillDir, ...versionFiles(view).map((f) => f.path)],
+				files: [...files, ...versionFiles(view)],
+				message: `${plugin}: update ${args.skill} skill (${to})`,
+				slug: `${plugin}-${to}`,
+				prBody: `Updates the skill \`${args.skill}\` in \`${plugin}\` and bumps it to ${to}.\n\nChanged: ${changeList(cmp.changes)}.`,
+				verify: [{ dir: skillDir, files: committed }],
+				state,
+			}),
+			installStep(view, installs, to, state),
+			{
+				id: "local-copy",
+				label: "settled the local copy",
+				outside: true,
+				async run() {
+					const copy = await settleLocalCopy({
+						folder,
+						committed,
+						copy: { scope: copyScope, name: args.skill },
+						keepReason,
+						moved: state.moved === true,
+						plugin,
+						pluginId,
+						cwd,
+					});
+					// A kept copy now matches the pushed commit: that is its base
+					// for the next publish, bound to it by a fresh token.
+					if (
+						copy.action === "kept" &&
+						!copy.partial &&
+						!managed &&
+						state.commit
+					) {
+						recordBase(folder, {
+							marketplace: m.name,
+							repo: m.source,
+							plugin,
+							skill: args.skill,
+							commit: state.commit,
+							tree: cmp.sets.hash,
+						});
+					}
+					return { patch: { localCopy: copy } };
+				},
+			},
+		];
+
+		const lines = [
+			`Publishes ${copyWord} of ${args.skill} to ${pluginId}`,
+			compareLine,
+			versionLine(plugin, from, to),
+			`Changes ${plural(cmp.changes.length, "file")} in the ${args.skill} skill: ${changeList(cmp.changes)}`,
+			...(cmp.sets.untrackedFolder
+				? [
+						"This folder is not tracked in the project's git; every file is listed",
+					]
+				: []),
+			...(cmp.sets.notPublished.length > 0
+				? [
+						`Not published: ${cmp.sets.notPublished.map((n) => `${n.path} (${n.reason})`).join(", ")}`,
+					]
+				: []),
+			targetLine(target, snap.branch),
+			"A pull request moves no install and keeps the local copy",
+			...installLines(plugin, installs, to),
+			predicted.action === "removed"
+				? `Afterwards removes ${copyWord} of ${args.skill}`
+				: `Keeps ${copyWord} of ${args.skill}: ${predicted.reason}`,
+		];
+		const plan: MarketPlan = {
+			command,
+			lines,
+			planId: computePlanId({
+				op: "publish",
+				skill: args.skill,
+				from: args.from,
+				keepLocal: args.keepLocal,
+				force: args.force,
+				compare: cmp.state,
+				base: cmp.baseCommit,
+				plugin: pluginId,
+				branch: snap.branch,
+				commit: snap.commit,
+				hash: cmp.sets.hash,
+				notPublished: cmp.sets.notPublished,
+				target,
+				version: { from, to },
+				installs,
+				localCopy: predicted,
+			}),
+			summary: {
+				...base,
+				version: { from, to },
+				files,
+				target,
+			},
+			steps,
+			sync: { name: m.name, url: cloneUrl(m.source) },
+			lock: m.name,
+			replan: () =>
+				planPublish({ ...args, plugin: args.plugin ?? pluginId }, cwd),
+			doneMessage: `${args.skill} is published in ${pluginId} ${to}. Takes effect in new sessions, or after /reload-plugins.`,
+			...(forced
+				? { secondConfirm: `Replace the plugin's version of ${args.skill}?` }
+				: {}),
+		};
+		return { kind: "plan", plan };
+	} catch (error) {
+		return planError(command, error);
+	}
+}
+
+// ─── publish a plugin ────────────────────────────────────────────────────────
+
+export interface PluginPublishArgs {
+	/** `plugin@marketplace`; the marketplace may be left out when there is one. */
+	plugin: string;
+	keepLocal: boolean;
+}
+
+const STATE_WORDS: Record<"no-base" | "conflict", string> = {
+	"no-base": "origin unknown",
+	conflict: "changed here and on GitHub",
+};
+
+/** One local copy a plugin-wide publish sends. */
+interface PublishedCopy {
+	skill: string;
+	from: "project" | "global";
+	folder: string;
+	skillDir: string;
+	cmp: LocalCompare;
+	committed: SkillFile[];
+	keepReason: string | null;
+	managed: boolean;
+	predicted: LocalCopy;
+}
+
+/**
+ * `market publish --plugin <p@m>` with no skill: every skill of the plugin
+ * whose local copy here has edits the plugin has not seen (`edited` in
+ * `market status`), sent as one commit and one patch version. A copy whose
+ * origin is unknown, or that changed on both sides, is listed and left out:
+ * it goes on its own, by name, with --force. Read-only.
+ */
+export async function planPluginPublish(
+	args: PluginPublishArgs,
+	cwd: string,
+): Promise<PlanAnswer> {
+	const command: MarketCommand = "market publish";
+	try {
+		const view = await readPlugin(args.plugin);
+		const { m, snap, plugin } = view;
+		const pluginId = `${plugin}@${m.name}`;
+		const prefix = joinRel(view.dir, "skills", "");
+		const skills = new Set<string>();
+		for (const p of snap.entries.keys()) {
+			if (!p.startsWith(`${prefix}/`)) continue;
+			const rest = p.slice(prefix.length + 1).split("/");
+			if (rest.length === 2 && rest[1] === "SKILL.md" && rest[0]) {
+				skills.add(rest[0]);
+			}
+		}
+		const folders = localSkillFolders(cwd).filter((f) => skills.has(f.skill));
+		const edited: Array<{ f: LocalFolder; cmp: LocalCompare }> = [];
+		const leftOut: Array<{
+			skill: string;
+			from: "project" | "global";
+			state: "no-base" | "conflict";
+		}> = [];
+		for (const f of folders) {
+			const cmp = await compareLocal(f.path, view, f.skill);
+			if (cmp.state === "fast") edited.push({ f, cmp });
+			else if (cmp.state === "no-base" || cmp.state === "conflict") {
+				leftOut.push({
+					skill: f.skill,
+					from: f.from === "user" ? "global" : "project",
+					state: cmp.state,
+				});
+			}
+		}
+		const twice = edited.find(
+			(e, i) => edited.findIndex((o) => o.f.skill === e.f.skill) !== i,
+		);
+		if (twice) {
+			throw new MarketError(
+				"ambiguous",
+				`Both this project and your USER skills have edits to ${twice.f.skill}`,
+				`publish one at a time: \`magus market publish ${twice.f.skill} --plugin ${pluginId} --from project\` (or --from global)`,
+			);
+		}
+		const leftOutLines = leftOut.map(
+			(l) =>
+				`Not included: ${l.skill} (${STATE_WORDS[l.state]}) — publish it on its own with \`magus market publish ${l.skill} --plugin ${pluginId}${l.from === "global" ? " --from global" : ""} --force\``,
+		);
+		const base = { marketplace: m.name, plugin };
+		if (edited.length === 0) {
+			if (leftOut.length > 0) {
+				const message = `No skill of ${pluginId} has edits here that it can publish as they are — nothing changed`;
+				return {
+					kind: "result",
+					result: {
+						command,
+						outcome: "failed",
+						message,
+						...base,
+						plan: leftOutLines,
+						steps: [],
+						error: {
+							code: leftOut[0]?.state ?? "no-base",
+							message,
+							fix: "publish each one on its own with --force, which asks before it replaces the plugin's version",
+						},
+					},
+				};
+			}
+			return {
+				kind: "result",
+				result: {
+					command,
+					outcome: "unchanged",
+					message: `No skill of ${pluginId} has edits here to publish`,
+					...base,
+					steps: [],
+				},
+			};
+		}
+
+		const { from, to } = bumpFrom(view);
+		const target = await deliveryTarget(m.source, m.name);
+		const installs = await installedScopes(pluginId, cwd);
+		const copies: PublishedCopy[] = [];
+		for (const { f, cmp } of edited) {
+			const fromWord = f.from === "user" ? "global" : "project";
+			const committed: SkillFile[] = [
+				...cmp.sets.published,
+				...cmp.theirsOut.map((t) => ({ path: t.path, oid: t.oid })),
+			];
+			const { reason, managed } = await keepReasonFor({
+				folder: f.path,
+				skill: f.skill,
+				from: fromWord,
+				keepLocal: args.keepLocal,
+				plugin,
+				pluginId,
+				installs,
+				committed,
+				cwd,
+			});
+			const scope = f.from;
+			copies.push({
+				skill: f.skill,
+				from: fromWord,
+				folder: f.path,
+				skillDir: joinRel(view.dir, "skills", f.skill),
+				cmp,
+				committed,
+				keepReason: reason,
+				managed,
+				predicted: reason
+					? { scope, name: f.skill, action: "kept", reason }
+					: { scope, name: f.skill, action: "removed" },
+			});
+		}
+		const files = [
+			...copies.flatMap((c) =>
+				c.cmp.changes.map((ch) => ({
+					path: joinRel(c.skillDir, ch.path),
+					change: ch.change,
+				})),
+			),
+			...versionFiles(view),
+		];
+		const names = copies.map((c) => c.skill);
+		const state: ChangeSpec["state"] & { moved?: boolean } = {};
+		const steps: MarketStep[] = [
+			...copies.map((c) =>
+				replaceStep(
+					c.folder,
+					c.skillDir,
+					plugin,
+					c.skill,
+					c.cmp,
+					c.committed,
+					`replace:${c.skill}`,
+				),
+			),
+			bumpStep(view, to),
+			...changeSteps({
+				label: m.name,
+				source: m.source,
+				branch: snap.branch,
+				target,
+				stage: [
+					...copies.map((c) => c.skillDir),
+					...versionFiles(view).map((f) => f.path),
+				],
+				files,
+				message: `${plugin}: update ${names.join(", ")} (${to})`,
+				slug: `${plugin}-${to}`,
+				prBody: `Updates ${plural(names.length, "skill")} in \`${plugin}\` and bumps it to ${to}.\n\n${copies.map((c) => `- \`${c.skill}\`: ${changeList(c.cmp.changes)}`).join("\n")}`,
+				verify: copies.map((c) => ({ dir: c.skillDir, files: c.committed })),
+				state,
+			}).map((s) =>
+				s.id === "deliver"
+					? {
+							...s,
+							// A pull request stops the apply here: nothing is installed,
+							// so every local copy stays until it is merged.
+							run: async (ctx: Parameters<MarketStep["run"]>[0]) => {
+								const out = await s.run(ctx);
+								if (!out?.stop) return out;
+								const kept: LocalCopy[] = copies.map((c) => ({
+									scope: c.predicted.scope,
+									name: c.skill,
+									action: "kept",
+									reason:
+										"the change went out as a pull request; the plugin's version replaces this copy once it is merged",
+								}));
+								return {
+									...out,
+									patch: { ...out.patch, localCopies: kept },
+								};
+							},
+						}
+					: s,
+			),
+			installStep(view, installs, to, state),
+			{
+				id: "local-copy",
+				label: "settled the local copies",
+				outside: true,
+				async run() {
+					const settled: LocalCopy[] = [];
+					for (const c of copies) {
+						const copy = await settleLocalCopy({
+							folder: c.folder,
+							committed: c.committed,
+							copy: { scope: c.predicted.scope, name: c.skill },
+							keepReason: c.keepReason,
+							moved: state.moved === true,
+							plugin,
+							pluginId,
+							cwd,
+						});
+						if (
+							copy.action === "kept" &&
+							!copy.partial &&
+							!c.managed &&
+							state.commit
+						) {
+							recordBase(c.folder, {
+								marketplace: m.name,
+								repo: m.source,
+								plugin,
+								skill: c.skill,
+								commit: state.commit,
+								tree: c.cmp.sets.hash,
+							});
+						}
+						settled.push(copy);
+					}
+					return { patch: { localCopies: settled } };
+				},
+			},
+		];
+		const lines = [
+			`Publishes ${plural(copies.length, "edited skill")} to ${pluginId} as one new version: ${names.join(", ")}`,
+			versionLine(plugin, from, to),
+			...copies.flatMap((c) => [
+				`${c.skill} (${whoseCopy(c.from)}): ${plural(c.cmp.changes.length, "file")} — ${changeList(c.cmp.changes)}`,
+				...(c.cmp.sets.notPublished.length > 0
+					? [
+							`${c.skill}, not published: ${c.cmp.sets.notPublished.map((n) => `${n.path} (${n.reason})`).join(", ")}`,
+						]
+					: []),
+			]),
+			...leftOutLines,
+			targetLine(target, snap.branch),
+			"A pull request moves no install and keeps the local copies",
+			...installLines(plugin, installs, to),
+			...copies.map((c) =>
+				c.predicted.action === "removed"
+					? `Afterwards removes ${whoseCopy(c.from)} of ${c.skill}`
+					: `Keeps ${whoseCopy(c.from)} of ${c.skill}: ${c.predicted.reason}`,
+			),
+		];
+		const plan: MarketPlan = {
+			command,
+			lines,
+			planId: computePlanId({
+				op: "publish-plugin",
+				plugin: pluginId,
+				keepLocal: args.keepLocal,
+				branch: snap.branch,
+				commit: snap.commit,
+				skills: copies.map((c) => ({
+					skill: c.skill,
+					from: c.from,
+					base: c.cmp.baseCommit,
+					hash: c.cmp.sets.hash,
+					notPublished: c.cmp.sets.notPublished,
+					localCopy: c.predicted,
+				})),
+				leftOut,
+				target,
+				version: { from, to },
+				installs,
+			}),
+			summary: { ...base, version: { from, to }, files, target },
+			steps,
+			sync: { name: m.name, url: cloneUrl(m.source) },
+			lock: m.name,
+			replan: () => planPluginPublish({ ...args, plugin: pluginId }, cwd),
+			doneMessage: `${names.join(", ")} ${names.length === 1 ? "is" : "are"} published in ${pluginId} ${to}. Takes effect in new sessions, or after /reload-plugins.`,
+		};
+		return { kind: "plan", plan };
+	} catch (error) {
+		return planError(command, error);
+	}
+}
+
+function capital(text: string): string {
+	return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+/** Remove `rel`'s now-empty parent directories, up to (not including) `root`. */
+function pruneEmptyParents(root: string, rel: string): void {
+	let dir = path.posix.dirname(rel);
+	while (dir !== "." && dir !== "") {
+		try {
+			fs.rmdirSync(path.join(root, dir));
+		} catch {
+			return;
+		}
+		dir = path.posix.dirname(dir);
+	}
+}
+
+/**
+ * Replace the in-domain part of the plugin's skill with the published set:
+ * write every published file, delete in-domain files the copy no longer has,
+ * leave everything outside the domain as it is. Then check the result holds
+ * exactly the committed files, the published ones with their planned ids.
+ */
+function replaceStep(
+	folder: string,
+	skillDir: string,
+	plugin: string,
+	skill: string,
+	cmp: LocalCompare,
+	committed: readonly SkillFile[],
+	id = "replace",
+): MarketStep {
+	return {
+		id,
+		label: `copied ${skill} into ${plugin}`,
+		outside: false,
+		async run(ctx) {
+			const clone = cloneOf(ctx);
+			const dest = path.join(clone, skillDir);
+			const changed = new MarketError(
+				"plan-changed",
+				`${skill} changed while this ran — nothing was pushed`,
+				"run the command again to see the new plan",
+			);
+			// A link committed in the marketplace would carry a write or a
+			// delete outside the clone: refuse before touching anything.
+			const linked = (link: string) =>
+				new MarketError(
+					"other",
+					`${plugin} holds a link at ${link}, and ${skill} would be written through it — nothing was changed`,
+					"replace the link with a folder in the marketplace repository, then publish again",
+				);
+			for (const f of [...cmp.theirsIn, ...cmp.sets.published]) {
+				refuseLinkUnder(clone, joinRel(skillDir, f.path), linked);
+			}
+			const keep = new Set(cmp.sets.published.map((f) => f.path));
+			// The compare is by content: a file the plugin already holds keeps
+			// its committed mode, so a mode that differs only here is neither an
+			// unplanned change nor a silently lost executable bit.
+			const modes = new Map(cmp.theirsIn.map((f) => [f.path, f.mode]));
+			for (const f of cmp.theirsIn) {
+				if (keep.has(f.path)) continue;
+				fs.rmSync(path.join(dest, f.path), { force: true });
+				pruneEmptyParents(dest, f.path);
+			}
+			for (const f of cmp.sets.published) {
+				const out = path.join(dest, f.path);
+				fs.mkdirSync(path.dirname(out), { recursive: true });
+				refuseLinkUnder(clone, joinRel(skillDir, f.path), linked);
+				// A new file every time: never written through what was there.
+				fs.rmSync(out, { force: true });
+				fs.copyFileSync(
+					path.join(folder, f.path),
+					out,
+					fs.constants.COPYFILE_EXCL,
+				);
+				const mode = modes.get(f.path);
+				if (mode === "100755") fs.chmodSync(out, 0o755);
+				else if (mode === "100644") fs.chmodSync(out, 0o644);
+			}
+			const want = new Set(committed.map((f) => f.path));
+			const now = inventory(dest);
+			if (now.length !== want.size || now.some((i) => !want.has(i.path))) {
+				throw changed;
+			}
+			const ids = await hashObject(
+				dest,
+				cmp.sets.published.map((f) => f.path),
+			);
+			if (
+				!ids.ok ||
+				cmp.sets.published.some((f, i) => ids.value[i] !== f.oid)
+			) {
+				throw changed;
+			}
+			return undefined;
+		},
+	};
+}
+
+/**
+ * A publish dry run on state older than GitHub's: what the local copy holds,
+ * and no compare. Nothing is decided from it.
+ */
+export function provisionalPublish(
+	args: PublishArgs,
+	cwd: string,
+	error: MarketError,
+): MarketResult {
+	const command: MarketCommand = "market publish";
+	let lines: string[] = [];
+	try {
+		const folder = sourceFolder(cwd, args);
+		const items = inventory(folder);
+		const shaped = items.map((i) => ({
+			path: i.path,
+			why: excludedByShape(i.path, i.symlink),
+		}));
+		const kept = shaped.filter((s) => s.why === null).map((s) => s.path);
+		const left = shaped.filter((s) => s.why !== null);
+		lines = [
+			`Would publish ${whoseCopy(args.from)} of ${args.skill}${args.plugin ? ` to ${args.plugin}` : ""}`,
+			`Files here: ${kept.join(", ") || "none"}`,
+			...(left.length > 0
+				? [
+						`Never published: ${left.map((s) => `${s.path} (${s.why})`).join(", ")}`,
+					]
+				: []),
+			"Not compared with the plugin: GitHub's current state could not be read",
+		];
+	} catch (inner) {
+		return errorResult(command, inner);
+	}
+	return {
+		command,
+		outcome: "stale",
+		stale: true,
+		message: `Provisional — ${error.message}. Nothing was compared or changed.`,
+		skill: args.skill,
+		plan: lines,
+		steps: [],
+		error: {
+			code: error.code,
+			message: error.message,
+			fix: error.fix ?? "run `magus market fetch`",
+		},
+	};
+}