gsd-pi 2.20.0 → 2.22.0

package/dist/resources/extensions/gsd/namespaced-registry.ts

@@ -0,0 +1,467 @@
+/**
+ * Namespaced Component Registry Module
+ *
+ * Provides the canonical identity model for imported plugin components.
+ * Supports both namespaced (plugin:component) and flat (bare name) components,
+ * detects collisions at registration time, and provides lookup by canonical name
+ * or namespace listing.
+ *
+ * This registry serves as the bridge between S01's plugin discovery output
+ * and Pi's internal component resolution system.
+ */
+
+import type { DiscoveredPlugin } from './marketplace-discovery.js';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Component type enumeration.
+ * Matches the component categories discovered by S01.
+ */
+export type ComponentType = 'skill' | 'agent';
+
+/**
+ * A component entry in the namespaced registry.
+ *
+ * Components can be:
+ * - Namespaced: `${namespace}:${name}` (e.g., "my-plugin:code-review")
+ * - Flat: `${name}` (e.g., "code-review" for backward compatibility)
+ */
+export interface NamespacedComponent {
+	/** The component's local name (e.g., "code-review") */
+	name: string;
+
+	/** The plugin namespace (e.g., "my-plugin"). Undefined for flat components. */
+	namespace: string | undefined;
+
+	/** The computed canonical identifier: `${namespace}:${name}` or bare `name` */
+	canonicalName: string;
+
+	/** Component type: skill or agent */
+	type: ComponentType;
+
+	/** Absolute path to the component's definition file */
+	filePath: string;
+
+	/** Source identifier (e.g., "plugin:my-plugin", "user", "project") */
+	source: string;
+
+	/** Optional description from the component's frontmatter */
+	description: string | undefined;
+
+	/** Extensible metadata bag for plugin origin info */
+	metadata: {
+		/** Plugin version if available */
+		pluginVersion?: string;
+		/** Plugin author if available */
+		pluginAuthor?: string;
+		/** Plugin homepage if available */
+		pluginHomepage?: string;
+		/** Plugin category if available */
+		pluginCategory?: string;
+		/** Original component directory name */
+		componentDir?: string;
+		/** Additional plugin-specific metadata */
+		[key: string]: unknown;
+	};
+}
+
+/**
+ * Collision information for registry diagnostics.
+ * Mirrors the ResourceCollision pattern from pi-coding-agent.
+ */
+export interface RegistryCollision {
+	/** The canonical name that collided (e.g., "my-plugin:code-review") */
+	canonicalName: string;
+
+	/** Path to the component that won (first registered) */
+	winnerPath: string;
+
+	/** Path to the component that lost (subsequent duplicate) */
+	loserPath: string;
+
+	/** Source of the winning component */
+	winnerSource?: string;
+
+	/** Source of the losing component */
+	loserSource?: string;
+}
+
+/**
+ * Diagnostic entry for registry operations.
+ * Currently only reports collisions, but extensible for future diagnostics.
+ */
+export interface RegistryDiagnostic {
+	/** Diagnostic type */
+	type: 'collision';
+
+	/** Human-readable message */
+	message: string;
+
+	/** Collision details */
+	collision: RegistryCollision;
+}
+
+/**
+ * Result of an alias registration attempt.
+ * Successful registrations return success: true.
+ * Failed registrations return success: false with a reason.
+ */
+export interface AliasRegistrationResult {
+	/** Whether the registration succeeded */
+	success: boolean;
+
+	/** On failure, the reason for rejection */
+	reason?: 'canonical-not-found' | 'shadows-canonical' | 'duplicate-alias';
+
+	/** Human-readable message */
+	message?: string;
+}
+
+// ============================================================================
+// NamespacedRegistry Class
+// ============================================================================
+
+/**
+ * Registry for namespaced plugin components.
+ *
+ * Features:
+ * - Computes canonical names from namespace + name
+ * - Detects and reports collisions at registration time
+ * - First registration wins; subsequent duplicates return diagnostic
+ * - Lookup by canonical name or namespace listing
+ * - Compatible with both namespaced and flat (non-namespaced) components
+ *
+ * Usage:
+ * ```typescript
+ * const registry = new NamespacedRegistry();
+ *
+ * // Register a namespaced component
+ * const diag = registry.register({
+ *   name: 'code-review',
+ *   namespace: 'my-plugin',
+ *   type: 'skill',
+ *   filePath: '/plugins/my-plugin/skills/code-review/SKILL.md',
+ *   source: 'plugin:my-plugin',
+ *   description: 'Reviews code for quality issues',
+ *   metadata: { pluginVersion: '1.0.0' }
+ * });
+ *
+ * // Lookup by canonical name
+ * const skill = registry.getByCanonical('my-plugin:code-review');
+ *
+ * // List all components in a namespace
+ * const allSkills = registry.getByNamespace('my-plugin');
+ * ```
+ */
+export class NamespacedRegistry {
+	/** Internal storage: canonicalName -> component */
+	private components = new Map<string, NamespacedComponent>();
+
+	/** Internal storage: alias -> canonicalName */
+	private aliasMap = new Map<string, string>();
+
+	/** Collision diagnostics collected during registration */
+	private diagnostics: RegistryDiagnostic[] = [];
+
+	/**
+	 * Register a component in the registry.
+	 *
+	 * Computes the canonical name as `${namespace}:${name}` when namespace is present,
+	 * or bare `name` otherwise. Returns a diagnostic if the canonical name already exists.
+	 *
+	 * @param component - Component data (without canonicalName, which is computed)
+	 * @returns Diagnostic if collision detected, undefined otherwise
+	 */
+	register(component: Omit<NamespacedComponent, 'canonicalName'>): RegistryDiagnostic | undefined {
+		// Compute canonical name
+		const canonicalName = component.namespace
+			? `${component.namespace}:${component.name}`
+			: component.name;
+
+		// Create full component with canonical name
+		const fullComponent: NamespacedComponent = {
+			...component,
+			canonicalName,
+		};
+
+		// Check for collision
+		const existing = this.components.get(canonicalName);
+		if (existing) {
+			const diagnostic: RegistryDiagnostic = {
+				type: 'collision',
+				message: `canonical name "${canonicalName}" collision`,
+				collision: {
+					canonicalName,
+					winnerPath: existing.filePath,
+					loserPath: component.filePath,
+					winnerSource: existing.source,
+					loserSource: component.source,
+				},
+			};
+			this.diagnostics.push(diagnostic);
+			return diagnostic;
+		}
+
+		// Register the component
+		this.components.set(canonicalName, fullComponent);
+		return undefined;
+	}
+
+	/**
+	 * Get a component by its canonical name.
+	 *
+	 * @param canonicalName - The canonical name (e.g., "my-plugin:code-review" or "code-review")
+	 * @returns The component if found, undefined otherwise
+	 */
+	getByCanonical(canonicalName: string): NamespacedComponent | undefined {
+		return this.components.get(canonicalName);
+	}
+
+	/**
+	 * Get all components belonging to a specific namespace.
+	 *
+	 * @param namespace - The namespace to filter by (e.g., "my-plugin")
+	 * @returns Array of components in that namespace
+	 */
+	getByNamespace(namespace: string): NamespacedComponent[] {
+		const results: NamespacedComponent[] = [];
+		for (const component of this.components.values()) {
+			if (component.namespace === namespace) {
+				results.push(component);
+			}
+		}
+		return results;
+	}
+
+	/**
+	 * Get all registered components.
+	 *
+	 * @returns Array of all components
+	 */
+	getAll(): NamespacedComponent[] {
+		return Array.from(this.components.values());
+	}
+
+	/**
+	 * Get all diagnostics collected during registration.
+	 *
+	 * Returns deep copies to prevent external mutation of internal state.
+	 *
+	 * @returns Array of diagnostics (collisions, etc.)
+	 */
+	getDiagnostics(): RegistryDiagnostic[] {
+		return this.diagnostics.map((d) => ({
+			type: d.type,
+			message: d.message,
+			collision: { ...d.collision },
+		}));
+	}
+
+	/**
+	 * Check if a canonical name is already registered.
+	 *
+	 * @param canonicalName - The canonical name to check
+	 * @returns true if registered, false otherwise
+	 */
+	has(canonicalName: string): boolean {
+		return this.components.has(canonicalName);
+	}
+
+	/**
+	 * Get the count of registered components.
+	 *
+	 * @returns Number of components
+	 */
+	get size(): number {
+		return this.components.size;
+	}
+
+	// ============================================================================
+	// Alias Management
+	// ============================================================================
+
+	/**
+	 * Register an alias for a canonical name.
+	 *
+	 * Validates:
+	 * 1. The target canonical name must exist
+	 * 2. The alias cannot shadow an existing canonical name
+	 * 3. The alias cannot already exist pointing to a different target
+	 *
+	 * @param alias - The short alias (e.g., "py3d")
+	 * @param canonicalName - The target canonical name (e.g., "python-tools:3d-visualizer")
+	 * @returns Result indicating success or failure with reason
+	 */
+	registerAlias(alias: string, canonicalName: string): AliasRegistrationResult {
+		// Check that target canonical name exists
+		if (!this.components.has(canonicalName)) {
+			return {
+				success: false,
+				reason: 'canonical-not-found',
+				message: `Cannot create alias "${alias}": target canonical name "${canonicalName}" does not exist`,
+			};
+		}
+
+		// Check that alias doesn't shadow an existing canonical name
+		if (this.components.has(alias)) {
+			return {
+				success: false,
+				reason: 'shadows-canonical',
+				message: `Cannot create alias "${alias}": it shadows an existing canonical name`,
+			};
+		}
+
+		// Check for duplicate alias pointing to different target
+		const existingTarget = this.aliasMap.get(alias);
+		if (existingTarget !== undefined && existingTarget !== canonicalName) {
+			return {
+				success: false,
+				reason: 'duplicate-alias',
+				message: `Cannot create alias "${alias}": already exists pointing to "${existingTarget}"`,
+			};
+		}
+
+		// Register the alias (idempotent if same target)
+		this.aliasMap.set(alias, canonicalName);
+
+		return { success: true };
+	}
+
+	/**
+	 * Remove an alias.
+	 *
+	 * @param alias - The alias to remove
+	 * @returns true if the alias existed and was removed, false otherwise
+	 */
+	removeAlias(alias: string): boolean {
+		return this.aliasMap.delete(alias);
+	}
+
+	/**
+	 * Resolve an alias to its canonical name.
+	 *
+	 * @param alias - The alias to resolve
+	 * @returns The canonical name if alias exists, undefined otherwise
+	 */
+	resolveAlias(alias: string): string | undefined {
+		return this.aliasMap.get(alias);
+	}
+
+	/**
+	 * Get all registered aliases.
+	 *
+	 * @returns A copy of the alias map (alias -> canonicalName)
+	 */
+	getAliases(): Map<string, string> {
+		return new Map(this.aliasMap);
+	}
+
+	/**
+	 * Check if an alias exists.
+	 *
+	 * @param alias - The alias to check
+	 * @returns true if the alias exists, false otherwise
+	 */
+	hasAlias(alias: string): boolean {
+		return this.aliasMap.has(alias);
+	}
+}
+
+// ============================================================================
+// Discovery Bridge Helper
+// ============================================================================
+
+/**
+ * Convert a discovered plugin's inventory into registerable component entries.
+ *
+ * This helper bridges S01's discovery output (DiscoveredPlugin) with the
+ * namespaced registry. It maps skill and agent directory names to component
+ * entries with the plugin's namespace.
+ *
+ * @param plugin - A discovered plugin from S01's discovery process
+ * @returns Array of registerable component entries (without canonicalName)
+ */
+export function componentsFromDiscovery(
+	plugin: DiscoveredPlugin
+): Omit<NamespacedComponent, 'canonicalName'>[] {
+	const components: Omit<NamespacedComponent, 'canonicalName'>[] = [];
+
+	// Use the plugin's canonical name as the namespace
+	const namespace = plugin.canonicalName;
+
+	// Extract common metadata from the plugin
+	const commonMetadata: NamespacedComponent['metadata'] = {
+		pluginVersion: plugin.version,
+		pluginAuthor: plugin.author?.name,
+		pluginHomepage: plugin.homepage,
+		pluginCategory: plugin.category,
+	};
+
+	// Process skills
+	for (const skillName of plugin.inventory.skills) {
+		// Resolve the skill file path
+		// Skills are in <plugin>/skills/<name>/SKILL.md or <plugin>/skills/<name>.md
+		let filePath: string;
+		if (plugin.resolvedPath) {
+			const skillDirPath = `${plugin.resolvedPath}/skills/${skillName}`;
+			// Prefer direct markdown file entries, otherwise directory with SKILL.md
+			filePath = skillName.endsWith('.md')
+				? `${plugin.resolvedPath}/skills/${skillName}`
+				: `${skillDirPath}/SKILL.md`;
+		} else {
+			// External plugin - use placeholder path
+			filePath = `<external>/${namespace}/skills/${skillName}/SKILL.md`;
+		}
+
+		components.push({
+			name: skillName.replace(/\.md$/, ''), // Strip .md if present
+			namespace,
+			type: 'skill',
+			filePath,
+			source: `plugin:${namespace}`,
+			description: undefined, // Would require reading the file
+			metadata: {
+				...commonMetadata,
+				componentDir: skillName,
+			},
+		});
+	}
+
+	// Process agents
+	for (const agentName of plugin.inventory.agents) {
+		// Resolve the agent file path
+		let filePath: string;
+		if (plugin.resolvedPath) {
+			const agentDirPath = `${plugin.resolvedPath}/agents/${agentName}`;
+			filePath = agentName.endsWith('.md')
+				? `${plugin.resolvedPath}/agents/${agentName}`
+				: `${agentDirPath}/AGENT.md`;
+		} else {
+			filePath = `<external>/${namespace}/agents/${agentName}/AGENT.md`;
+		}
+
+		components.push({
+			name: agentName.replace(/\.md$/, ''), // Strip .md if present
+			namespace,
+			type: 'agent',
+			filePath,
+			source: `plugin:${namespace}`,
+			description: undefined, // Would require reading the file
+			metadata: {
+				...commonMetadata,
+				componentDir: agentName,
+			},
+		});
+	}
+
+	return components;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default NamespacedRegistry;