gsd-pi 2.33.1 → 2.34.0-dev.6769913

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

@@ -0,0 +1,322 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// 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 */
+    components = new Map();
+    /** Internal storage: alias -> canonicalName */
+    aliasMap = new Map();
+    /** Collision diagnostics collected during registration */
+    diagnostics = [];
+    /**
+     * 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) {
+        // Compute canonical name
+        const canonicalName = component.namespace
+            ? `${component.namespace}:${component.name}`
+            : component.name;
+        // Create full component with canonical name
+        const fullComponent = {
+            ...component,
+            canonicalName,
+        };
+        // Check for collision
+        const existing = this.components.get(canonicalName);
+        if (existing) {
+            const diagnostic = {
+                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) {
+        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) {
+        const results = [];
+        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() {
+        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() {
+        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) {
+        return this.components.has(canonicalName);
+    }
+    /**
+     * Get the count of registered components.
+     *
+     * @returns Number of components
+     */
+    get size() {
+        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, canonicalName) {
+        // 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) {
+        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) {
+        return this.aliasMap.get(alias);
+    }
+    /**
+     * Get all registered aliases.
+     *
+     * @returns A copy of the alias map (alias -> canonicalName)
+     */
+    getAliases() {
+        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) {
+        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) {
+    const components = [];
+    // Use the plugin's canonical name as the namespace
+    const namespace = plugin.canonicalName;
+    // Extract common metadata from the plugin
+    const commonMetadata = {
+        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;
+        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;
+        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;

package/dist/resources/extensions/gsd/namespaced-resolver.js

@@ -0,0 +1,176 @@
+/**
+ * Namespaced Resolver Module
+ *
+ * Implements context-aware resolution with three-tier lookup precedence:
+ * 1. Canonical (fully-qualified names with `:`)
+ * 2. Local-first (caller namespace + bare name)
+ * 3. Shorthand (bare name matched across all namespaces)
+ *
+ * This is the core logic for D003 (same-plugin local-first) and R007/R008 (safe shorthand).
+ */
+// ============================================================================
+// NamespacedResolver Class
+// ============================================================================
+/**
+ * Resolver for namespaced components with context-aware lookup.
+ *
+ * Implements four-tier resolution precedence:
+ * 1. **Canonical**: If name contains `:`, try exact match → return canonical result
+ * 2. **Alias**: If name is a registered alias → return alias result
+ * 3. **Local-first**: If `context.callerNamespace` exists, try `${callerNamespace}:${name}` → return local-first result
+ * 4. **Shorthand**: Scan all components for bare name match → single match returns shorthand, multiple returns ambiguous
+ *
+ * Usage:
+ * ```typescript
+ * const registry = new NamespacedRegistry();
+ * // ... populate registry ...
+ * // ... register aliases ...
+ *
+ * const resolver = new NamespacedResolver(registry);
+ *
+ * // Canonical lookup
+ * const canon = resolver.resolve('farm:call-horse');
+ * // canon.resolution === 'canonical'
+ *
+ * // Alias resolution
+ * const alias = resolver.resolve('py3d');
+ * // alias.resolution === 'alias', alias.canonicalName === 'python-tools:3d-visualizer'
+ *
+ * // Local-first resolution from caller context
+ * const local = resolver.resolve('call-horse', { callerNamespace: 'farm' });
+ * // local.resolution === 'local-first'
+ *
+ * // Unambiguous shorthand
+ * const short = resolver.resolve('unique-skill');
+ * // short.resolution === 'shorthand'
+ *
+ * // Ambiguous shorthand
+ * const amb = resolver.resolve('common-skill');
+ * // amb.resolution === 'ambiguous', amb.candidates has all matches
+ * ```
+ */
+export class NamespacedResolver {
+    /** The registry to resolve against */
+    registry;
+    /**
+     * Create a new resolver for the given registry.
+     *
+     * @param registry - The namespaced registry to resolve against
+     */
+    constructor(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Resolve a component name with context-aware lookup.
+     *
+     * Implements four-tier resolution precedence:
+     * 1. **Canonical**: If name contains `:`, try exact match → return canonical result
+     * 2. **Alias**: If name is a registered alias → return alias result
+     * 3. **Local-first**: If `context.callerNamespace` exists, try `${callerNamespace}:${name}` → return local-first result
+     * 4. **Shorthand**: Scan all components for bare name match → single match returns shorthand, multiple returns ambiguous
+     *
+     * @param name - The name to resolve (canonical or bare)
+     * @param context - Optional resolution context with caller namespace
+     * @param type - Optional type filter (skill or agent)
+     * @returns Resolution result indicating how the match was found
+     */
+    resolve(name, context, type) {
+        // Tier 1: Canonical lookup (name contains `:`)
+        if (name.includes(':')) {
+            const component = this.registry.getByCanonical(name);
+            if (component && this.matchesType(component, type)) {
+                return {
+                    requestedName: name,
+                    resolution: 'canonical',
+                    component,
+                };
+            }
+            // Canonical name not found
+            return {
+                requestedName: name,
+                resolution: 'not-found',
+            };
+        }
+        // Tier 2: Alias lookup (before local-first and shorthand)
+        const aliasTarget = this.registry.resolveAlias(name);
+        if (aliasTarget) {
+            const component = this.registry.getByCanonical(aliasTarget);
+            if (component && this.matchesType(component, type)) {
+                return {
+                    requestedName: name,
+                    resolution: 'alias',
+                    component,
+                    alias: name,
+                    canonicalName: aliasTarget,
+                };
+            }
+        }
+        // Tier 3: Local-first resolution (if caller namespace provided)
+        if (context?.callerNamespace) {
+            const localCanonical = `${context.callerNamespace}:${name}`;
+            const component = this.registry.getByCanonical(localCanonical);
+            if (component && this.matchesType(component, type)) {
+                return {
+                    requestedName: name,
+                    resolution: 'local-first',
+                    component,
+                    matchedNamespace: context.callerNamespace,
+                };
+            }
+        }
+        // Tier 4: Shorthand resolution (scan all components)
+        const candidates = this.findBareNameMatches(name, type);
+        if (candidates.length === 0) {
+            return {
+                requestedName: name,
+                resolution: 'not-found',
+            };
+        }
+        if (candidates.length === 1) {
+            return {
+                requestedName: name,
+                resolution: 'shorthand',
+                component: candidates[0],
+            };
+        }
+        // Multiple matches - ambiguous
+        return {
+            requestedName: name,
+            resolution: 'ambiguous',
+            candidates,
+        };
+    }
+    /**
+     * Find all components whose local name (without namespace) matches the given bare name.
+     * Optionally filters by component type.
+     *
+     * @param bareName - The bare name to match
+     * @param type - Optional type filter
+     * @returns Array of matching components
+     */
+    findBareNameMatches(bareName, type) {
+        const all = this.registry.getAll();
+        return all.filter((component) => {
+            // Match by local name (component.name)
+            if (component.name !== bareName) {
+                return false;
+            }
+            // Apply type filter if provided
+            return this.matchesType(component, type);
+        });
+    }
+    /**
+     * Check if a component matches the optional type filter.
+     *
+     * @param component - The component to check
+     * @param type - Optional type filter
+     * @returns true if no filter or type matches
+     */
+    matchesType(component, type) {
+        return type === undefined || component.type === type;
+    }
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default NamespacedResolver;