@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/extensibility/plugins/marketplace/registry.ts

@@ -0,0 +1,196 @@
+/**
+ * Registry read/write operations for the marketplace plugin system.
+ *
+ * Two registries:
+ *   - marketplaces.json under getConfigRootDir() — which catalogs the user has added
+ *   - installed_plugins.json under getPluginsDir() — which plugins are installed
+ *
+ * Read/write functions accept explicit file paths so callers control the
+ * location. Path helpers compute the default paths from the dir singleton.
+ *
+ * Both use atomic write (tmp + rename). On Windows, rename over existing file
+ * can fail with EPERM — fallback: unlink target then rename.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import { getConfigRootDir, getPluginsDir, isEnoent, logger, tryParseJson } from "@f5xc-salesdemos/pi-utils";
+
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+	MarketplaceRegistryEntry,
+	MarketplacesRegistry,
+} from "./types";
+
+// ── Path helpers ─────────────────────────────────────────────────────
+
+export function getMarketplacesRegistryPath(): string {
+	return path.join(getConfigRootDir(), "marketplaces.json");
+}
+
+export function getInstalledPluginsRegistryPath(): string {
+	return path.join(getPluginsDir(), "installed_plugins.json");
+}
+
+export function getMarketplacesCacheDir(): string {
+	return path.join(getPluginsDir(), "cache", "marketplaces");
+}
+
+export function getPluginsCacheDir(): string {
+	return path.join(getPluginsDir(), "cache", "plugins");
+}
+
+// ── Atomic write ─────────────────────────────────────────────────────
+
+async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
+	const content = `${JSON.stringify(data, null, 2)}\n`;
+	const tmpPath = `${filePath}.tmp`;
+
+	await Bun.write(tmpPath, content);
+
+	try {
+		await fs.rename(tmpPath, filePath);
+	} catch (err) {
+		// Windows EPERM fallback: unlink target, then rename
+		if ((err as NodeJS.ErrnoException).code === "EPERM") {
+			try {
+				await fs.unlink(filePath);
+			} catch {
+				// Target may not exist — that's fine
+			}
+			await fs.rename(tmpPath, filePath);
+		} else {
+			// Clean up tmp on unexpected errors
+			try {
+				await fs.unlink(tmpPath);
+			} catch {
+				// Best effort
+			}
+			throw err;
+		}
+	}
+}
+
+// ── Marketplaces registry ────────────────────────────────────────────
+
+function emptyMarketplacesRegistry(): MarketplacesRegistry {
+	return { version: 1, marketplaces: [] };
+}
+
+export async function readMarketplacesRegistry(filePath: string): Promise<MarketplacesRegistry> {
+	try {
+		const content = await Bun.file(filePath).text();
+		const data = tryParseJson<MarketplacesRegistry>(content);
+		if (!data || typeof data !== "object" || data.version !== 1 || !Array.isArray(data.marketplaces)) {
+			logger.warn("Invalid marketplaces registry, returning empty", { path: filePath });
+			return emptyMarketplacesRegistry();
+		}
+		return data;
+	} catch (err) {
+		if (isEnoent(err)) return emptyMarketplacesRegistry();
+		throw err;
+	}
+}
+
+export async function writeMarketplacesRegistry(filePath: string, reg: MarketplacesRegistry): Promise<void> {
+	await atomicWriteJson(filePath, reg);
+}
+
+// ── Installed plugins registry ───────────────────────────────────────
+
+function emptyInstalledPluginsRegistry(): InstalledPluginsRegistry {
+	return { version: 2, plugins: {} };
+}
+
+export async function readInstalledPluginsRegistry(filePath: string): Promise<InstalledPluginsRegistry> {
+	try {
+		const content = await Bun.file(filePath).text();
+		const data = tryParseJson<InstalledPluginsRegistry>(content);
+		if (
+			!data ||
+			typeof data !== "object" ||
+			typeof data.version !== "number" ||
+			!data.plugins ||
+			typeof data.plugins !== "object" ||
+			Array.isArray(data.plugins)
+		) {
+			logger.warn("Invalid installed plugins registry, returning empty", { path: filePath });
+			return emptyInstalledPluginsRegistry();
+		}
+		// Accept any numeric version — forward compatible reads
+		return { ...data, version: 2 };
+	} catch (err) {
+		if (isEnoent(err)) return emptyInstalledPluginsRegistry();
+		throw err;
+	}
+}
+
+export async function writeInstalledPluginsRegistry(filePath: string, reg: InstalledPluginsRegistry): Promise<void> {
+	await atomicWriteJson(filePath, reg);
+}
+
+// ── Marketplace CRUD ─────────────────────────────────────────────────
+// Pure functions that transform registry state. Caller is responsible for
+// reading, mutating, and writing back.
+
+export function addMarketplaceEntry(reg: MarketplacesRegistry, entry: MarketplaceRegistryEntry): MarketplacesRegistry {
+	if (reg.marketplaces.some(m => m.name === entry.name)) {
+		throw new Error(`Marketplace "${entry.name}" already exists`);
+	}
+	return { ...reg, marketplaces: [...reg.marketplaces, entry] };
+}
+
+export function removeMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplacesRegistry {
+	const filtered = reg.marketplaces.filter(m => m.name !== name);
+	if (filtered.length === reg.marketplaces.length) {
+		throw new Error(`Marketplace "${name}" not found`);
+	}
+	return { ...reg, marketplaces: filtered };
+}
+
+export function getMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplaceRegistryEntry | undefined {
+	return reg.marketplaces.find(m => m.name === name);
+}
+
+// ── Installed plugin CRUD ────────────────────────────────────────────
+
+export function addInstalledPlugin(
+	reg: InstalledPluginsRegistry,
+	id: string,
+	entry: InstalledPluginEntry,
+): InstalledPluginsRegistry {
+	const existing = reg.plugins[id] ?? [];
+	return {
+		...reg,
+		plugins: { ...reg.plugins, [id]: [...existing, entry] },
+	};
+}
+
+export function removeInstalledPlugin(reg: InstalledPluginsRegistry, id: string): InstalledPluginsRegistry {
+	if (!(id in reg.plugins)) {
+		throw new Error(`Plugin "${id}" not found in registry`);
+	}
+	const { [id]: _, ...rest } = reg.plugins;
+	return { ...reg, plugins: rest };
+}
+
+export function getInstalledPlugin(reg: InstalledPluginsRegistry, id: string): InstalledPluginEntry[] | undefined {
+	return reg.plugins[id];
+}
+
+/**
+ * Collect all installPath values referenced by any of the provided registries.
+ * Use this before deleting a cached plugin directory to verify it is not still
+ * referenced by another scope's registry.
+ */
+export function collectReferencedPaths(...registries: InstalledPluginsRegistry[]): Set<string> {
+	return new Set(
+		registries.flatMap(r =>
+			Object.values(r.plugins)
+				.flat()
+				.map(e => e.installPath),
+		),
+	);
+}

package/src/extensibility/plugins/marketplace/source-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * Source resolver for marketplace plugin entries.
+ *
+ * Resolves plugin sources to absolute local directory paths:
+ *   - Relative string "./plugins/foo" → path within marketplace clone
+ *   - { source: "url", url: "https://...git" } → git clone
+ *   - { source: "github", repo: "owner/repo" } → git clone from GitHub
+ *   - { source: "git-subdir", url: "...", path: "sub/dir" } → git clone + subdir
+ *   - { source: "npm", ... } → not yet supported
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import { isEnoent, pathIsWithin } from "@f5xc-salesdemos/pi-utils";
+import * as git from "../../../utils/git";
+
+import type { MarketplaceCatalogMetadata, MarketplacePluginEntry, PluginSource } from "./types";
+
+export interface ResolveContext {
+	/** Absolute path to the cloned/local marketplace directory. Required for relative sources. */
+	marketplaceClonePath?: string;
+	/** Catalog metadata — used for `pluginRoot` prepend. */
+	catalogMetadata?: MarketplaceCatalogMetadata;
+	/** Scratch directory for sources that require cloning or extraction. */
+	tmpDir: string;
+}
+
+/**
+ * Resolve a plugin source to an absolute local directory path.
+ *
+ * The resolved path is verified to exist on disk.
+ */
+export async function resolvePluginSource(
+	entry: MarketplacePluginEntry,
+	context: ResolveContext,
+): Promise<{ dir: string; tempCloneRoot?: string }> {
+	const { source } = entry;
+
+	if (typeof source === "string") {
+		return resolveRelativeSource(source, context);
+	}
+
+	return resolveObjectSource(source, context);
+}
+
+// ── Relative string source ("./plugins/foo") ────────────────────────
+
+async function resolveRelativeSource(
+	source: string,
+	context: ResolveContext,
+): Promise<{ dir: string; tempCloneRoot?: string }> {
+	if (!source.startsWith("./")) {
+		throw new Error(`Relative plugin source paths must start with "./" — got: "${source}"`);
+	}
+
+	if (!context.marketplaceClonePath) {
+		throw new Error(`Cannot resolve relative source "${source}": marketplaceClonePath is required`);
+	}
+
+	// If pluginRoot is set, prepend it to the path segment after "./"
+	const pluginRoot = context.catalogMetadata?.pluginRoot;
+	const relativePath = pluginRoot ? `./${path.join(pluginRoot, source.slice(2))}` : source;
+
+	// Resolve against marketplace root (not the .claude-plugin/ catalog subdirectory)
+	const resolved = path.resolve(context.marketplaceClonePath, relativePath);
+
+	if (!pathIsWithin(context.marketplaceClonePath, resolved)) {
+		throw new Error(
+			`Plugin source "${source}" resolves outside marketplace root ("${context.marketplaceClonePath}")`,
+		);
+	}
+
+	await verifyDirExists(resolved, `Plugin source directory does not exist: "${resolved}"`);
+	return { dir: resolved };
+}
+
+// ── Object source variants ──────────────────────────────────────────
+
+async function resolveObjectSource(
+	source: Exclude<PluginSource, string>,
+	context: ResolveContext,
+): Promise<{ dir: string; tempCloneRoot?: string }> {
+	switch (source.source) {
+		case "url": {
+			// { source: "url", url: "https://github.com/owner/repo.git" }
+			// Despite the name, this is typically a git clone URL
+			const targetDir = path.join(context.tmpDir, `plugin-${crypto.randomUUID()}`);
+			await git.clone(source.url, targetDir, { ref: source.ref, sha: source.sha });
+			return { dir: targetDir, tempCloneRoot: targetDir };
+		}
+
+		case "github": {
+			// { source: "github", repo: "owner/repo" }
+			const url = `https://github.com/${source.repo}.git`;
+			const targetDir = path.join(context.tmpDir, `plugin-${crypto.randomUUID()}`);
+			await git.clone(url, targetDir, { ref: source.ref, sha: source.sha });
+			return { dir: targetDir, tempCloneRoot: targetDir };
+		}
+
+		case "git-subdir": {
+			// { source: "git-subdir", url: "owner/repo" | "https://...", path: "plugins/foo" }
+			const url =
+				source.url.includes("://") || source.url.startsWith("git@")
+					? source.url
+					: `https://github.com/${source.url}.git`;
+			const cloneDir = path.join(context.tmpDir, `plugin-repo-${crypto.randomUUID()}`);
+			await git.clone(url, cloneDir, { ref: source.ref, sha: source.sha });
+
+			const subdirPath = path.resolve(cloneDir, source.path);
+			if (!pathIsWithin(cloneDir, subdirPath)) {
+				await fs.rm(cloneDir, { recursive: true, force: true });
+				throw new Error(`git-subdir path "${source.path}" escapes the cloned repository`);
+			}
+			try {
+				await verifyDirExists(subdirPath, `git-subdir path "${source.path}" does not exist in cloned repository`);
+			} catch (err) {
+				await fs.rm(cloneDir, { recursive: true, force: true });
+				throw err;
+			}
+			return { dir: subdirPath, tempCloneRoot: cloneDir };
+		}
+
+		case "npm":
+			throw new Error("npm plugin sources are not yet supported. Use git-based sources instead.");
+
+		default:
+			throw new Error(`Unknown plugin source type: "${(source as { source: string }).source}"`);
+	}
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+async function verifyDirExists(dirPath: string, errorMessage: string): Promise<void> {
+	try {
+		const stat = await fs.stat(dirPath);
+		if (!stat.isDirectory()) {
+			throw new Error(errorMessage);
+		}
+	} catch (err) {
+		if (isEnoent(err)) {
+			throw new Error(errorMessage);
+		}
+		throw err;
+	}
+}

package/src/extensibility/plugins/marketplace/types.ts

@@ -0,0 +1,191 @@
+/**
+ * Marketplace plugin system types.
+ *
+ * Two registries:
+ *   - MarketplacesRegistry: which marketplace catalogs the user has added (config)
+ *   - InstalledPluginsRegistry: which plugins are installed (data, Claude Code-compatible)
+ *
+ * The installed registry MUST pass `parseClaudePluginsRegistry()` validation —
+ * it uses `version: 2` (numeric) and `plugins: Record<string, ...[]>`.
+ */
+
+// ── Plugin ID helpers ────────────────────────────────────────────────
+
+const NAME_RE = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
+const MAX_NAME_LENGTH = 64;
+const MAX_ID_LENGTH = 128;
+
+/** Validate a plugin or marketplace name segment. */
+export function isValidNameSegment(s: string): boolean {
+	return s.length > 0 && s.length <= MAX_NAME_LENGTH && NAME_RE.test(s);
+}
+
+/** Build canonical plugin ID: `"name@marketplace"`. Both segments are validated. */
+export function buildPluginId(name: string, marketplace: string): string {
+	if (!isValidNameSegment(name)) {
+		throw new Error(`Invalid plugin name: "${name}"`);
+	}
+	if (!isValidNameSegment(marketplace)) {
+		throw new Error(`Invalid marketplace name: "${marketplace}"`);
+	}
+	const id = `${name}@${marketplace}`;
+	if (id.length > MAX_ID_LENGTH) {
+		throw new Error(`Plugin ID exceeds ${MAX_ID_LENGTH} characters: "${id}"`);
+	}
+	return id;
+}
+
+/** Parse `"name@marketplace"` → `{ name, marketplace }` or `null`. */
+export function parsePluginId(id: string): { name: string; marketplace: string } | null {
+	const atIndex = id.lastIndexOf("@");
+	if (atIndex <= 0 || atIndex === id.length - 1) return null;
+
+	const name = id.slice(0, atIndex);
+	const marketplace = id.slice(atIndex + 1);
+
+	if (!isValidNameSegment(name) || !isValidNameSegment(marketplace)) return null;
+
+	return { name, marketplace };
+}
+
+// ── Marketplace catalog (from marketplace.json in a marketplace repo) ─
+
+export interface MarketplaceCatalogOwner {
+	name: string;
+	email?: string;
+}
+
+export interface MarketplaceCatalogMetadata {
+	description?: string;
+	version?: string;
+	/** If set, prepended to relative plugin source paths. */
+	pluginRoot?: string;
+}
+
+export interface MarketplaceCatalog {
+	name: string;
+	owner: MarketplaceCatalogOwner;
+	metadata?: MarketplaceCatalogMetadata;
+	plugins: MarketplacePluginEntry[];
+}
+
+export interface MarketplacePluginAuthor {
+	name: string;
+	email?: string;
+}
+
+export interface MarketplacePluginEntry {
+	name: string;
+	source: PluginSource;
+	description?: string;
+	version?: string;
+	author?: MarketplacePluginAuthor;
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	category?: string;
+	tags?: string[];
+	strict?: boolean;
+	commands?: string | string[];
+	agents?: string | string[];
+	hooks?: string | Record<string, unknown>;
+	mcpServers?: string | Record<string, unknown>;
+	lspServers?: string | Record<string, unknown>;
+}
+
+// ── Plugin source variants ───────────────────────────────────────────
+
+export type PluginSource =
+	| string // relative path "./plugins/foo"
+	| PluginSourceGitHub
+	| PluginSourceUrl
+	| PluginSourceGitSubdir
+	| PluginSourceNpm;
+
+export interface PluginSourceGitHub {
+	source: "github";
+	repo: string;
+	ref?: string;
+	sha?: string;
+}
+
+export interface PluginSourceUrl {
+	source: "url";
+	url: string;
+	ref?: string;
+	sha?: string;
+}
+
+export interface PluginSourceGitSubdir {
+	source: "git-subdir";
+	url: string;
+	path: string;
+	ref?: string;
+	sha?: string;
+}
+
+export interface PluginSourceNpm {
+	source: "npm";
+	package: string;
+	version?: string;
+	registry?: string;
+}
+
+// ── Marketplaces registry (stored in <configRoot>/marketplaces.json) ─
+
+export interface MarketplacesRegistry {
+	version: 1;
+	marketplaces: MarketplaceRegistryEntry[];
+}
+
+export type MarketplaceSourceType = "github" | "git" | "url" | "local";
+
+export interface MarketplaceRegistryEntry {
+	name: string;
+	sourceType: MarketplaceSourceType;
+	sourceUri: string;
+	catalogPath: string;
+	addedAt: string;
+	updatedAt: string;
+}
+
+// ── Installed plugins registry ───────────────────────────────────────
+// MUST match ClaudePluginsRegistry shape for parseClaudePluginsRegistry()
+// compatibility: `version: number`, `plugins: Record<string, entry[]>`.
+
+export interface InstalledPluginsRegistry {
+	/** MUST be 2 — parseClaudePluginsRegistry rejects non-numeric version. */
+	version: 2;
+	plugins: Record<string, InstalledPluginEntry[]>;
+}
+
+export interface InstalledPluginEntry {
+	scope: "user" | "project";
+	/** Absolute path to cached plugin directory. */
+	installPath: string;
+	version: string;
+	/** ISO 8601 date string. */
+	installedAt: string;
+	/** ISO 8601 date string. */
+	lastUpdated: string;
+	/** For git-sourced plugins. */
+	gitCommitSha?: string;
+	/** OMP extension — not in Claude Code's type. CLI/UI concern only in v1. */
+	enabled?: boolean;
+}
+
+/**
+ * A merged view of an installed plugin, combining entries from both the user and
+ * project registries. Returned by MarketplaceManager.listInstalledPlugins().
+ *
+ * `shadowedBy` is set on user-scoped summaries when the same plugin ID also exists
+ * in the project registry — the project entry takes precedence for capability loading.
+ */
+export interface InstalledPluginSummary {
+	id: string;
+	scope: "user" | "project";
+	entries: InstalledPluginEntry[];
+	/** Set when a user-scoped plugin is overridden by a project-scoped install. */
+	shadowedBy?: "project";
+}

package/src/extensibility/plugins/parser.ts

@@ -0,0 +1,105 @@
+/**
+ * Feature bracket parser for plugin specifiers.
+ *
+ * Supports syntax like:
+ * - "my-plugin" -> base features (null)
+ * - "my-plugin[search,web]" -> specific features
+ * - "my-plugin[*]" -> all features
+ * - "my-plugin[]" -> no optional features
+ * - "@scope/plugin@1.2.3[feat]" -> scoped with version and features
+ */
+
+export interface ParsedPluginSpec {
+	/** Package name (may include version specifier like @1.0.0) */
+	packageName: string;
+	/**
+	 * Feature selection:
+	 * - null: use defaults (base features on first install, preserve on reinstall)
+	 * - "*": all features
+	 * - string[]: specific features (empty array = no optional features)
+	 */
+	features: string[] | null | "*";
+}
+
+/**
+ * Parse plugin specifier with feature bracket syntax.
+ *
+ * @example
+ * parsePluginSpec("my-plugin") // { packageName: "my-plugin", features: null }
+ * parsePluginSpec("my-plugin[search,web]") // { packageName: "my-plugin", features: ["search", "web"] }
+ * parsePluginSpec("my-plugin[*]") // { packageName: "my-plugin", features: "*" }
+ * parsePluginSpec("my-plugin[]") // { packageName: "my-plugin", features: [] }
+ * parsePluginSpec("@scope/pkg@1.2.3[feat]") // { packageName: "@scope/pkg@1.2.3", features: ["feat"] }
+ */
+export function parsePluginSpec(spec: string): ParsedPluginSpec {
+	// Find the last bracket pair (to handle version specifiers like @1.0.0)
+	const bracketStart = spec.lastIndexOf("[");
+	const bracketEnd = spec.lastIndexOf("]");
+
+	// No brackets or malformed -> base features
+	if (bracketStart === -1 || bracketEnd === -1 || bracketEnd < bracketStart) {
+		return { packageName: spec, features: null };
+	}
+
+	const packageName = spec.slice(0, bracketStart);
+	const featureStr = spec.slice(bracketStart + 1, bracketEnd).trim();
+
+	// All features
+	if (featureStr === "*") {
+		return { packageName, features: "*" };
+	}
+
+	// No optional features
+	if (featureStr === "") {
+		return { packageName, features: [] };
+	}
+
+	// Specific features (comma-separated)
+	const features = featureStr
+		.split(",")
+		.map(f => f.trim())
+		.filter(Boolean);
+
+	return { packageName, features };
+}
+
+/**
+ * Format a parsed plugin spec back to string form.
+ *
+ * @example
+ * formatPluginSpec({ packageName: "pkg", features: null }) // "pkg"
+ * formatPluginSpec({ packageName: "pkg", features: "*" }) // "pkg[*]"
+ * formatPluginSpec({ packageName: "pkg", features: [] }) // "pkg[]"
+ * formatPluginSpec({ packageName: "pkg", features: ["a", "b"] }) // "pkg[a,b]"
+ */
+export function formatPluginSpec(spec: ParsedPluginSpec): string {
+	if (spec.features === null) {
+		return spec.packageName;
+	}
+	if (spec.features === "*") {
+		return `${spec.packageName}[*]`;
+	}
+	if (spec.features.length === 0) {
+		return `${spec.packageName}[]`;
+	}
+	return `${spec.packageName}[${spec.features.join(",")}]`;
+}
+
+/**
+ * Extract the base package name without version specifier.
+ * Used for path lookups after npm install.
+ *
+ * @example
+ * extractPackageName("lodash@4.17.21") // "lodash"
+ * extractPackageName("@scope/pkg@1.0.0") // "@scope/pkg"
+ * extractPackageName("@scope/pkg") // "@scope/pkg"
+ */
+export function extractPackageName(specifier: string): string {
+	// Handle scoped packages: @scope/name@version -> @scope/name
+	if (specifier.startsWith("@")) {
+		const match = specifier.match(/^(@[^/]+\/[^@]+)/);
+		return match ? match[1] : specifier;
+	}
+	// Unscoped: name@version -> name
+	return specifier.replace(/@[^@]+$/, "");
+}