magus-cli 7.12.2 → 7.14.0

package/src/services/market-install.ts

@@ -0,0 +1,172 @@
+/**
+ * market-install.ts — move a plugin's installs to a version just published,
+ * through Claude Code's CLI and nothing else.
+ *
+ * The only things this module may call are `runPluginVerb` (spawns `claude
+ * plugin install|update`), `readInstalledVersionForScope` and
+ * `loadedVersionHere` (both only read `installed_plugins.json`). None of them
+ * reaches a function that writes Claude Code's files directly, so nothing here
+ * can repair, redirect or rewrite an install: a scope Claude Code did not move
+ * is reported as not moved, with `magus update` as the fix.
+ *
+ * Keep the import list exactly as it is. Anything more is a path to a direct
+ * writer of Claude Code's state.
+ */
+
+import { type PluginScope, runPluginVerb } from "./claude-cli.js";
+import { loadedVersionHere } from "./claude-settings.js";
+import { readInstalledVersionForScope } from "./plugin-manager.js";
+
+/** What happened at one scope. */
+export interface InstallMove {
+	scope: PluginScope;
+	/** This folder's own row at the scope before the verb; null when none. */
+	from: string | null;
+	/** The row after every verb ran; null when there is none. */
+	to: string | null;
+	/** The version Claude Code loads in this folder, read once after every verb. */
+	loaded: string | null;
+	status: "updated" | "unchanged" | "failed";
+	message?: string;
+	fix?: string;
+}
+
+export interface AdvanceResult {
+	installs: InstallMove[];
+	/** The version Claude Code loads in this folder after the move. */
+	loaded: string | null;
+	/** `partial` when any scope failed or this folder does not load the target. */
+	outcome: "ok" | "partial";
+	message?: string;
+	fix?: string;
+}
+
+/** The three calls {@link advanceViaCli} makes; replaceable for tests. */
+export interface AdvanceDeps {
+	runPluginVerb: typeof runPluginVerb;
+	readInstalledVersionForScope: typeof readInstalledVersionForScope;
+	loadedVersionHere: typeof loadedVersionHere;
+}
+
+const realDeps: AdvanceDeps = {
+	runPluginVerb,
+	readInstalledVersionForScope,
+	loadedVersionHere,
+};
+
+const FIX = "magus update";
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Bring `pluginId` to `target` at each of `scopes`, as seen from `cwd`.
+ *
+ * Two passes. First the verbs, scope by scope: `update` where this folder
+ * already has a row at that scope, else `install`. Then one read-back, after
+ * every verb has run: each scope's own row, and once the version the loader
+ * picks in this folder. Judging the loaded version inside the first pass
+ * would depend on registry order, since the loader takes the first relevant
+ * row, not the one just moved.
+ *
+ * Each scope is judged by its own row. The move as a whole is judged by what
+ * this folder loads. Claude Code's marketplace clone must already hold the
+ * new version: `claude plugin update` does not fetch it.
+ */
+export async function advanceViaCli(
+	pluginId: string,
+	scopes: readonly PluginScope[],
+	cwd: string,
+	target: string,
+	deps: AdvanceDeps = realDeps,
+): Promise<AdvanceResult> {
+	const pending: Array<{
+		scope: PluginScope;
+		from: string | null;
+		error?: string;
+	}> = [];
+
+	for (const scope of scopes) {
+		let from: string | null = null;
+		try {
+			from = await deps.readInstalledVersionForScope(pluginId, scope, cwd);
+			await deps.runPluginVerb(
+				from ? "update" : "install",
+				pluginId,
+				scope,
+				cwd,
+			);
+			pending.push({ scope, from });
+		} catch (error) {
+			pending.push({ scope, from, error: errorText(error) });
+		}
+	}
+
+	const loaded = await deps.loadedVersionHere(pluginId, cwd);
+	const installs: InstallMove[] = [];
+	for (const { scope, from, error } of pending) {
+		let to: string | null = null;
+		try {
+			to = await deps.readInstalledVersionForScope(pluginId, scope, cwd);
+		} catch (readError) {
+			installs.push({
+				scope,
+				from,
+				to: null,
+				loaded,
+				status: "failed",
+				message: `could not read what Claude Code installed: ${errorText(readError)}`,
+				fix: FIX,
+			});
+			continue;
+		}
+		if (error !== undefined) {
+			installs.push({
+				scope,
+				from,
+				to,
+				loaded,
+				status: "failed",
+				message: error,
+				...(/not found in marketplace/i.test(error) ? { fix: FIX } : {}),
+			});
+			continue;
+		}
+		if (to === target) {
+			installs.push({
+				scope,
+				from,
+				to,
+				loaded,
+				status: from === target ? "unchanged" : "updated",
+			});
+			continue;
+		}
+		installs.push({
+			scope,
+			from,
+			to,
+			loaded,
+			status: "failed",
+			message: `Claude Code did not move this folder to v${target}`,
+			fix: FIX,
+		});
+	}
+
+	if (scopes.length > 0 && loaded !== target) {
+		return {
+			installs,
+			loaded,
+			outcome: "partial",
+			message: loaded
+				? `installed v${target}, but this folder still loads v${loaded}`
+				: `installed v${target}, but this folder loads no version of it`,
+			fix: FIX,
+		};
+	}
+	const failed = installs.some((i) => i.status === "failed");
+	return failed
+		? { installs, loaded, outcome: "partial", fix: FIX }
+		: { installs, loaded, outcome: "ok" };
+}

package/src/services/market-layout.ts

@@ -0,0 +1,311 @@
+/**
+ * market-layout.ts — pure rules about how a marketplace repository is laid out.
+ *
+ * Nothing here reads or writes the disk: every function takes what it needs
+ * and answers. The scan, dependency resolution and the market verbs all ask
+ * the same question — where does this plugin live in its marketplace? — and
+ * get one answer.
+ */
+
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+/** True when `child` is `root` or sits below it. Both must be absolute. */
+function isInside(root: string, child: string): boolean {
+	const rel = path.relative(root, child);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/**
+ * The directory a plugin entry's `source` names inside a marketplace, or null
+ * when it names none there.
+ *
+ * Claude Code's two relative forms:
+ * - `"./plugins/kit"` (or `"../…"`, `"."`) is relative to the marketplace root.
+ * - A bare name, `"kit"`, resolves under `metadata.pluginRoot` — a relative
+ *   path inside the marketplace such as `"./plugins"`. With no `pluginRoot`,
+ *   or one pointing outside the marketplace, a bare name does not resolve.
+ *
+ * Anything else — an object source (a git repository, a URL), an absolute
+ * path, or a path that leaves the marketplace — is not a directory here.
+ */
+export function pluginDirFor(
+	marketplaceRoot: string,
+	source: unknown,
+	pluginRoot?: unknown,
+): string | null {
+	if (typeof source !== "string" || source.trim() === "") return null;
+	if (path.isAbsolute(source)) return null;
+	const root = path.resolve(marketplaceRoot);
+
+	const relative =
+		source === "." ||
+		source === ".." ||
+		source.startsWith("./") ||
+		source.startsWith("../");
+	if (relative) {
+		const dir = path.resolve(root, source);
+		return isInside(root, dir) ? dir : null;
+	}
+
+	if (typeof pluginRoot !== "string" || pluginRoot.trim() === "") return null;
+	if (path.isAbsolute(pluginRoot)) return null;
+	const base = path.resolve(root, pluginRoot);
+	if (!isInside(root, base)) return null;
+	const dir = path.resolve(base, source);
+	return isInside(base, dir) ? dir : null;
+}
+
+// ─── Names ───────────────────────────────────────────────────────────────────
+
+/** A marketplace or plugin name: lower case, digits and dashes. */
+const PACKAGE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A skill folder name: letters, digits, dots, dashes and underscores. */
+const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+/** True for a marketplace or plugin name magus will write. */
+export function validPackageName(name: string): boolean {
+	return PACKAGE_NAME.test(name);
+}
+
+/** True for a skill folder name: one path segment, never `.` or `..`. */
+export function validSkillName(name: string): boolean {
+	return SKILL_NAME.test(name);
+}
+
+/**
+ * A plugin's directory relative to the marketplace root, with forward
+ * slashes ("" for the root itself), or null when its source names no
+ * directory inside it.
+ */
+export function pluginRelDir(
+	source: unknown,
+	pluginRoot?: unknown,
+): string | null {
+	const root = path.resolve(path.sep, "marketplace-root");
+	const dir = pluginDirFor(root, source, pluginRoot);
+	if (dir === null) return null;
+	return path.relative(root, dir).split(path.sep).join("/");
+}
+
+// ─── Manifest entries ────────────────────────────────────────────────────────
+
+export interface PluginEntry {
+	name: string;
+	source?: unknown;
+	version?: unknown;
+	description?: unknown;
+	[key: string]: unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The manifest's plugin entries that carry a name. */
+export function pluginEntries(manifest: unknown): PluginEntry[] {
+	if (!isRecord(manifest) || !Array.isArray(manifest.plugins)) return [];
+	return manifest.plugins.filter(
+		(p): p is PluginEntry => isRecord(p) && typeof p.name === "string",
+	);
+}
+
+/** `metadata.pluginRoot`, when the manifest declares one. */
+export function pluginRootOf(manifest: unknown): unknown {
+	if (!isRecord(manifest) || !isRecord(manifest.metadata)) return undefined;
+	return manifest.metadata.pluginRoot;
+}
+
+/** The manifest with `entry` appended to `plugins`. Returns a copy. */
+export function addPluginEntry<T extends Record<string, unknown>>(
+	manifest: T,
+	entry: PluginEntry,
+): T {
+	const plugins = Array.isArray(manifest.plugins) ? manifest.plugins : [];
+	return { ...manifest, plugins: [...plugins, entry] };
+}
+
+/** The manifest without the entry named `name`. Returns a copy. */
+export function removePluginEntry<T extends Record<string, unknown>>(
+	manifest: T,
+	name: string,
+): T {
+	const plugins = Array.isArray(manifest.plugins) ? manifest.plugins : [];
+	return {
+		...manifest,
+		plugins: plugins.filter((p) => !(isRecord(p) && p.name === name)),
+	};
+}
+
+/** The manifest with the entry named `name` at `version`. Returns a copy. */
+export function setEntryVersion<T extends Record<string, unknown>>(
+	manifest: T,
+	name: string,
+	version: string,
+): T {
+	const plugins = Array.isArray(manifest.plugins) ? manifest.plugins : [];
+	return {
+		...manifest,
+		plugins: plugins.map((p) =>
+			isRecord(p) && p.name === name ? { ...p, version } : p,
+		),
+	};
+}
+
+// ─── Versions ────────────────────────────────────────────────────────────────
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * The version a plugin is at: `plugin.json`'s `version` first (what Claude
+ * Code honours when both exist), else the marketplace entry's, else null for
+ * an unversioned plugin.
+ */
+export function currentVersion(
+	pluginJson: unknown,
+	entry: unknown,
+): string | null {
+	for (const source of [pluginJson, entry]) {
+		if (isRecord(source) && typeof source.version === "string") {
+			const v = source.version.trim();
+			if (v) return v;
+		}
+	}
+	return null;
+}
+
+/**
+ * The patch bump of `current`; an unversioned plugin goes to `0.0.1`. Null
+ * when `current` is not `major.minor.patch`, which magus will not guess at.
+ */
+export function nextVersion(current: string | null): string | null {
+	if (current === null) return "0.0.1";
+	const m = SEMVER.exec(current);
+	if (!m) return null;
+	return `${m[1]}.${m[2]}.${Number(m[3]) + 1}`;
+}
+
+// ─── Ownership ───────────────────────────────────────────────────────────────
+
+export interface OwnerCandidate {
+	marketplace: string;
+	/** Each plugin with its directory relative to the root (null: none here). */
+	plugins: Array<{ name: string; dir: string | null }>;
+	/** Every file path in the marketplace at the commit read. */
+	paths: ReadonlySet<string>;
+}
+
+/** Every `plugin@marketplace` whose plugin holds `skills/<skill>/SKILL.md`. */
+export function findSkillOwners(
+	candidates: readonly OwnerCandidate[],
+	skill: string,
+): string[] {
+	const owners: string[] = [];
+	for (const c of candidates) {
+		for (const p of c.plugins) {
+			if (p.dir === null) continue;
+			const file = joinRel(p.dir, "skills", skill, "SKILL.md");
+			if (c.paths.has(file)) owners.push(`${p.name}@${c.marketplace}`);
+		}
+	}
+	return owners;
+}
+
+/** Join path segments with `/`, dropping empty ones (a plugin at the root). */
+export function joinRel(...parts: string[]): string {
+	return parts.filter((p) => p !== "" && p !== ".").join("/");
+}
+
+// ─── Copy sets ───────────────────────────────────────────────────────────────
+
+/** The file mode git records for a symlink. */
+export const SYMLINK_MODE = "120000";
+
+/**
+ * Why a path inside a skill folder is never copied, by path and mode alone,
+ * or null when it may be: a symlink, any segment starting with `.`, or a path
+ * under `node_modules/`.
+ */
+export function excludedByShape(
+	relPath: string,
+	symlink: boolean,
+): "symlink" | "dotfile" | "node_modules" | null {
+	if (symlink) return "symlink";
+	const segments = relPath.split("/");
+	if (segments.some((s) => s.startsWith("."))) return "dotfile";
+	if (segments.includes("node_modules")) return "node_modules";
+	return null;
+}
+
+/**
+ * The compare domain: a path counts when its shape allows it and neither
+ * side ignores it. Decided from path and mode alone, so it applies equally to
+ * a file present on one side only.
+ */
+export function inDomain(
+	relPath: string,
+	mode: string,
+	ignoredHere: ReadonlySet<string>,
+	ignoredThere: ReadonlySet<string>,
+): boolean {
+	return (
+		excludedByShape(relPath, mode === SYMLINK_MODE) === null &&
+		!ignoredHere.has(relPath) &&
+		!ignoredThere.has(relPath)
+	);
+}
+
+/** A file in a skill: its path inside the skill folder and its blob id. */
+export interface SkillFile {
+	path: string;
+	oid: string;
+}
+
+/** One hash for a file set, the same function for a stored tree and a folder. */
+export function treeHash(files: readonly SkillFile[]): string {
+	const lines = [...files]
+		.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+		.map((f) => `${f.oid} ${f.path}`)
+		.join("\n");
+	return createHash("sha256").update(lines).digest("hex");
+}
+
+/**
+ * How a local copy of a skill stands against its plugin, from three tree
+ * hashes over the compare domain: `base` (what the copy started from; null
+ * when there is no record), `theirs` (the plugin now) and `ours` (the copy).
+ *
+ * - `same`: the copy equals the plugin; nothing to publish.
+ * - `plugin-newer`: the copy has no edits and the plugin moved on.
+ * - `fast`: the plugin has not changed since the copy was made.
+ * - `no-base`: nobody knows what the copy started from.
+ * - `conflict`: both the copy and the plugin changed.
+ */
+export type CompareState =
+	| "same"
+	| "fast"
+	| "plugin-newer"
+	| "no-base"
+	| "conflict";
+
+export function compareSkillTrees(
+	base: string | null,
+	theirs: string,
+	ours: string,
+): CompareState {
+	if (ours === theirs) return "same";
+	if (base === null) return "no-base";
+	if (ours === base) return "plugin-newer";
+	if (theirs === base) return "fast";
+	return "conflict";
+}
+
+/** True when both sets hold the same paths with the same blob ids. */
+export function sameFiles(
+	a: readonly SkillFile[],
+	b: readonly SkillFile[],
+): boolean {
+	if (a.length !== b.length) return false;
+	const map = new Map(a.map((f) => [f.path, f.oid]));
+	return b.every((f) => map.get(f.path) === f.oid);
+}

package/src/services/market-local.ts

@@ -0,0 +1,93 @@
+/**
+ * market-local.ts — the skills and plugins on this machine that no company
+ * marketplace holds yet: what the market screens offer to add to one.
+ *
+ * Read-only: folders are listed and two small files read, nothing written.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ORIGIN_FILE } from "./market-bases.js";
+import { profileManaged } from "./market-publish.js";
+import type { LocalItem } from "./market-types.js";
+import { getUserSkillsDir } from "./skills-manager.js";
+
+const PLUGIN_JSON = path.join(".claude-plugin", "plugin.json");
+
+function isFile(file: string): boolean {
+	try {
+		return fs.lstatSync(file).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/** The `name` a plugin folder's plugin.json gives, or null. */
+function pluginJsonName(folder: string): string | null {
+	try {
+		const json = JSON.parse(
+			fs.readFileSync(path.join(folder, PLUGIN_JSON), "utf8"),
+		) as { name?: unknown };
+		return typeof json.name === "string" && json.name.trim()
+			? json.name.trim()
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * This project's skills (`.claude/skills/<name>/`) and your USER skills
+ * (`<claude config dir>/skills/<name>/`), real folders only, as two kinds:
+ * - a plugin: the folder holds `.claude-plugin/plugin.json`, and no company
+ *   marketplace has a plugin of its name (`companyPlugins`) — once added,
+ *   the folder is the marketplace's plugin, not a local one;
+ * - a skill: the folder holds `SKILL.md`, and is none of a copy magus made of
+ *   a company skill (it holds `.magus-origin`), a skill a company plugin
+ *   holds under the same name (`companySkills`), or a skill folder this
+ *   project's profile installs.
+ * Sorted by name, project before USER for the same name.
+ */
+export async function localItems(
+	cwd: string,
+	companySkills: ReadonlySet<string>,
+	companyPlugins: ReadonlySet<string> = new Set(),
+): Promise<LocalItem[]> {
+	const roots = [
+		{ scope: "project" as const, dir: path.join(cwd, ".claude", "skills") },
+		{ scope: "user" as const, dir: getUserSkillsDir() },
+	];
+	const out: LocalItem[] = [];
+	const seen = new Set<string>();
+	for (const { scope, dir } of roots) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const d of entries) {
+			if (!d.isDirectory()) continue;
+			const folder = path.join(dir, d.name);
+			if (seen.has(folder)) continue;
+			seen.add(folder);
+			if (isFile(path.join(folder, PLUGIN_JSON))) {
+				const name = pluginJsonName(folder) ?? d.name;
+				if (!companyPlugins.has(name)) {
+					out.push({ kind: "plugin", name, scope, path: folder });
+				}
+				continue;
+			}
+			if (!isFile(path.join(folder, "SKILL.md"))) continue;
+			if (fs.existsSync(path.join(folder, ORIGIN_FILE))) continue;
+			if (companySkills.has(d.name)) continue;
+			if (scope === "project" && (await profileManaged(cwd, d.name))) continue;
+			out.push({ kind: "skill", name: d.name, scope, path: folder });
+		}
+	}
+	return out.sort((a, b) =>
+		a.name === b.name
+			? a.scope.localeCompare(b.scope)
+			: a.name.localeCompare(b.name),
+	);
+}

package/src/services/market-marker.ts

@@ -0,0 +1,49 @@
+/**
+ * market-marker.ts — the company marker in a marketplace manifest.
+ *
+ * A company marketplace says so in its own `.claude-plugin/marketplace.json`:
+ * `metadata.magus = {"schema": 1, "company": true}`. Claude Code ignores the
+ * field at load time; plain `claude plugin validate` reports it as a warning
+ * and still exits 0. `--strict` would fail on it, so magus never runs that.
+ *
+ * The marker alone does not make a marketplace company on this machine: the
+ * marketplace must also be on this machine's trust list, so a repository
+ * cannot promote itself by committing the field.
+ */
+
+export const MARKER_SCHEMA = 1;
+
+export interface MagusMarker {
+	schema: number;
+	company: boolean;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** True when the parsed manifest carries `metadata.magus.company === true`. */
+export function readMarker(manifest: unknown): boolean {
+	if (!isRecord(manifest)) return false;
+	const metadata = manifest.metadata;
+	if (!isRecord(metadata)) return false;
+	const magus = metadata.magus;
+	return isRecord(magus) && magus.company === true;
+}
+
+/**
+ * The manifest with the marker set. Returns a copy; every other field, and
+ * every other key under `metadata`, is kept as it was.
+ */
+export function withMarker<T extends Record<string, unknown>>(
+	manifest: T,
+): T & { metadata: Record<string, unknown> & { magus: MagusMarker } } {
+	const metadata = isRecord(manifest.metadata) ? manifest.metadata : {};
+	return {
+		...manifest,
+		metadata: {
+			...metadata,
+			magus: { schema: MARKER_SCHEMA, company: true },
+		},
+	};
+}