@launch77/plugin-runtime 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,3 +1,151 @@
+import fs from 'fs-extra';
+
+/**
+ * Type of location within a Launch77 workspace
+ */
+type Launch77LocationType = 'workspace-root' | 'workspace-app' | 'workspace-library' | 'workspace-plugin' | 'workspace-app-template' | 'unknown';
+/**
+ * Context information about the current location within a Launch77 workspace
+ */
+interface Launch77Context {
+    isValid: boolean;
+    locationType: Launch77LocationType;
+    workspaceRoot: string;
+    appsDir: string;
+    workspaceVersion: string;
+    workspaceName: string;
+    appName?: string;
+    packageName: string;
+}
+/**
+ * Workspace manifest structure (.launch77/workspace.json)
+ */
+interface WorkspaceManifest {
+    version: string;
+}
+/**
+ * Parsed location information from a path
+ */
+interface ParsedLocation {
+    locationType: Launch77LocationType;
+    appName?: string;
+}
+
+/**
+ * Service responsible for workspace manifest file operations.
+ * Handles reading and writing the .launch77/workspace.json file.
+ */
+declare class WorkspaceManifestService {
+    private static readonly WORKSPACE_MANIFEST;
+    /**
+     * Check if a workspace manifest exists at the given root
+     */
+    exists(workspaceRoot: string): Promise<boolean>;
+    /**
+     * Read the workspace manifest
+     */
+    readWorkspaceManifest(workspaceRoot: string): Promise<WorkspaceManifest | null>;
+    /**
+     * Write the workspace manifest
+     */
+    writeWorkspaceManifest(workspaceRoot: string, manifest: WorkspaceManifest): Promise<void>;
+    /**
+     * Get the manifest file path for a workspace
+     */
+    getManifestPath(workspaceRoot: string): string;
+}
+
+/**
+ * Validation result type
+ */
+interface ValidationResult$2 {
+    isValid: boolean;
+    errors?: string[];
+}
+/**
+ * Service responsible for workspace-related operations.
+ * Handles workspace detection and workspace queries.
+ */
+declare class WorkspaceService {
+    private workspaceManifestService;
+    constructor(workspaceManifestService?: WorkspaceManifestService);
+    /**
+     * Check if a directory is a Launch77 workspace root
+     */
+    isWorkspaceRoot(dir: string): Promise<boolean>;
+    /**
+     * Get the workspace root directory from the current directory
+     */
+    findWorkspaceRoot(startDir: string): Promise<string | null>;
+    /**
+     * Validate that we're in a Launch77 workspace context
+     */
+    validateWorkspaceContext(context: Launch77Context): Promise<{
+        valid: boolean;
+        errorMessage?: string;
+    }>;
+    /**
+     * Validate a workspace context using ValidationResult format
+     */
+    validateContext(context: Launch77Context): ValidationResult$2;
+    /**
+     * Validate an app name
+     */
+    validateAppName(name: string): ValidationResult$2;
+    /**
+     * Detect the Launch77 workspace context from the current working directory
+     *
+     * @param cwd - Current working directory path
+     * @returns Context information about the workspace location
+     */
+    detectLaunch77Context(cwd: string): Promise<Launch77Context>;
+}
+/**
+ * Standalone function for backward compatibility
+ * Creates a new WorkspaceService instance and calls detectLaunch77Context
+ */
+declare function detectLaunch77Context(cwd: string): Promise<Launch77Context>;
+
+/**
+ * Parse the directory structure to determine location context
+ *
+ * Based on patterns:
+ * - apps/[name] → workspace-app
+ * - libraries/[name] → workspace-library
+ * - plugins/[name] → workspace-plugin
+ * - app-templates/[name] → workspace-app-template
+ * - (empty or root) → workspace-root
+ *
+ * @param cwdPath - Current working directory path
+ * @param workspaceRoot - Root path of the workspace
+ * @returns Parsed location information
+ */
+declare function parseLocationFromPath(cwdPath: string, workspaceRoot: string): ParsedLocation;
+
+interface InstallPluginRequest {
+    pluginName: string;
+}
+interface InstallPluginResult {
+    pluginName: string;
+    filesInstalled: boolean;
+    packageJsonUpdated: boolean;
+    dependenciesInstalled: boolean;
+}
+interface HookResult {
+    templateVariables?: Record<string, string>;
+    hookContext?: Record<string, string>;
+}
+interface DeletePluginRequest {
+    pluginName: string;
+}
+interface DeletePluginResult {
+    pluginName: string;
+}
+type Target = 'app' | 'library' | 'plugin' | 'app-template';
+
+/**
+ * Plugin Module Types
+ */
 interface GeneratorContext {
     appPath: string;
     appName: string;
@@ -8,25 +156,10 @@ interface PluginMetadata {
     targets: string[];
     pluginDependencies?: Record<string, string>;
     libraryDependencies?: Record<string, string>;
-}
-interface InstalledPluginMetadata {
-    package: string;
-    version: string;
-    installedAt: string;
-    source: 'local' | 'npm';
+    showcaseUrl?: string;
 }
 interface TemplateMetadata {
 }
-interface TemplateReference {
-    package: string;
-    version: string;
-    source: 'local' | 'npm';
-    createdAt: string;
-}
-interface Launch77PackageManifest {
-    installedPlugins?: Record<string, InstalledPluginMetadata>;
-    template?: TemplateReference;
-}
 
 /**
  * Base abstract class for all plugin generators.
@@ -47,6 +180,106 @@ declare abstract class Generator {
     abstract run(): Promise<void>;
 }
 
+/**
+ * Service responsible for file system operations.
+ * Provides an abstraction layer over fs operations with proper error handling.
+ */
+declare class FilesystemService {
+    /**
+     * Check if a path exists
+     */
+    pathExists(filePath: string): Promise<boolean>;
+    /**
+     * Copy a file or directory recursively
+     */
+    copyRecursive(source: string, destination: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Read a JSON file
+     */
+    readJSON<T = unknown>(filePath: string): Promise<T>;
+    /**
+     * Write a JSON file
+     */
+    writeJSON(filePath: string, data: unknown, options?: {
+        spaces?: number;
+    }): Promise<void>;
+    /**
+     * Read a text file
+     */
+    readFile(filePath: string, encoding?: BufferEncoding): Promise<string>;
+    /**
+     * Write a text file
+     */
+    writeFile(filePath: string, content: string, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * Create a directory (including parent directories)
+     */
+    ensureDir(dirPath: string): Promise<void>;
+    /**
+     * Remove a file or directory
+     */
+    remove(filePath: string): Promise<void>;
+    /**
+     * List files in a directory
+     */
+    readDir(dirPath: string): Promise<string[]>;
+    /**
+     * Get file or directory stats
+     */
+    getStats(filePath: string): Promise<fs.Stats>;
+    /**
+     * Check if a path is a directory
+     */
+    isDirectory(filePath: string): Promise<boolean>;
+    /**
+     * Check if a path is a file
+     */
+    isFile(filePath: string): Promise<boolean>;
+    /**
+     * Move a file or directory
+     */
+    move(source: string, destination: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a temporary directory
+     */
+    createTempDir(prefix: string): Promise<string>;
+}
+
+/**
+ * Service responsible for reading and managing metadata for plugins and templates.
+ * Handles JSON file reading and parsing without mixing validation concerns.
+ */
+declare class MetadataService {
+    /**
+     * Read plugin metadata from a plugin directory
+     */
+    readPluginMetadata(pluginPath: string): Promise<PluginMetadata>;
+    /**
+     * Read template metadata from a template directory
+     */
+    readTemplateMetadata(templatePath: string): Promise<TemplateMetadata>;
+    /**
+     * Check if a plugin metadata file exists
+     */
+    hasPluginMetadata(pluginPath: string): Promise<boolean>;
+    /**
+     * Check if a template metadata file exists
+     */
+    hasTemplateMetadata(templatePath: string): Promise<boolean>;
+    /**
+     * Write plugin metadata to a directory
+     */
+    writePluginMetadata(pluginPath: string, metadata: PluginMetadata): Promise<void>;
+    /**
+     * Write template metadata to a directory
+     */
+    writeTemplateMetadata(templatePath: string, metadata: TemplateMetadata): Promise<void>;
+}
+
 /**
  * Standard generator with convention-over-configuration approach.
  *
@@ -60,6 +293,9 @@ declare abstract class Generator {
  * For full control, extend Generator instead.
  */
 declare abstract class StandardGenerator extends Generator {
+    protected filesystemService: FilesystemService;
+    protected metadataService: MetadataService;
+    constructor(context: GeneratorContext);
     run(): Promise<void>;
     protected updateDependencies(): Promise<void>;
     protected installDependencies(): Promise<void>;
@@ -68,168 +304,523 @@ declare abstract class StandardGenerator extends Generator {
     protected showNextSteps(): void;
 }
 
-declare function copyRecursive(src: string, dest: string): Promise<void>;
-declare function pathExists(filePath: string): Promise<boolean>;
-
 /**
- * Read and parse plugin metadata from plugin.json
- *
- * Only reads plugin-specific configuration fields:
- * - targets: where the plugin can be installed
- * - pluginDependencies: other plugins this plugin requires
- * - libraryDependencies: npm packages to inject into target
- *
- * Name and version are read from package.json during resolution.
- *
- * @param pluginPath - Absolute path to the plugin directory
- * @returns Parsed plugin metadata
+ * Validation result type for plugin operations
  */
-declare function readPluginMetadata(pluginPath: string): Promise<PluginMetadata>;
+interface ValidationResult$1 {
+    isValid: boolean;
+    errors?: string[];
+}
 /**
- * Read and parse template metadata from template.json
- *
- * Currently template.json contains no fields - it exists as a placeholder
- * for future template-specific configuration (e.g., deployment metadata).
- *
- * Template name and version are read from package.json during resolution.
- *
- * @param templatePath - Absolute path to the template directory
- * @returns Template metadata (currently empty)
+ * Plugin consistency error type
  */
-declare function readTemplateMetadata(templatePath: string): Promise<TemplateMetadata>;
+interface PluginConsistencyError {
+    library: string;
+    packageJsonVersion: string | 'MISSING';
+    pluginJsonVersion: string;
+}
+declare class PluginService {
+    private pluginResolver;
+    private metadataService;
+    private npmService;
+    constructor();
+    /**
+     * Validate a plugin name
+     */
+    validatePluginName(name: string): ValidationResult$1;
+    /**
+     * Validate plugin metadata
+     */
+    validatePluginMetadata(metadata: PluginMetadata): ValidationResult$1;
+    /**
+     * Validate a showcase URL
+     * Note: This is primarily used by the webapp template
+     */
+    validateShowcaseUrl(url: string | undefined): ValidationResult$1;
+    /**
+     * Validate plugin consistency between plugin.json and package.json
+     */
+    validatePluginConsistency(pluginPath: string): Promise<ValidationResult$1>;
+    /**
+     * Check if a package name part is valid
+     */
+    private isValidPackageNamePart;
+    /**
+     * Validate plugin name, resolve its location, and download if needed
+     */
+    private validateAndResolvePlugin;
+    /**
+     * Read plugin metadata and validate it supports the current target
+     */
+    private validatePluginTargets;
+    /**
+     * Check if plugin is already installed and return early-exit result if so
+     */
+    private checkExistingInstallation;
+    /**
+     * Install a plugin to the current package
+     */
+    installPlugin(request: InstallPluginRequest, context: Launch77Context, logger?: (message: string) => void): Promise<InstallPluginResult>;
+    /**
+     * Download and install an npm plugin package
+     */
+    private downloadNpmPlugin;
+    private getPackagePath;
+    private runGenerator;
+    private isPluginInstalled;
+    /**
+     * Write plugin installation metadata to the target package's package.json
+     */
+    private writePluginManifest;
+    /**
+     * Delete a plugin from the workspace
+     */
+    deletePlugin(request: DeletePluginRequest, context: Launch77Context): Promise<DeletePluginResult>;
+}
 
 /**
- * Type of location within a Launch77 workspace
+ * Metadata about an installed plugin
  */
-type Launch77LocationType = 'workspace-root' | 'workspace-app' | 'workspace-library' | 'workspace-plugin' | 'workspace-app-template' | 'unknown';
+interface InstalledPluginMetadata {
+    package: string;
+    version: string;
+    installedAt: string;
+    source: 'local' | 'npm';
+}
 /**
- * Context information about the current location within a Launch77 workspace
+ * Reference to the template used to create this package
  */
-interface Launch77Context {
-    isValid: boolean;
-    locationType: Launch77LocationType;
-    workspaceRoot: string;
-    appsDir: string;
-    workspaceVersion: string;
-    workspaceName: string;
-    appName?: string;
-    packageName: string;
+interface TemplateReference {
+    package: string;
+    version: string;
+    source: 'local' | 'npm';
+    createdAt: string;
+}
+/**
+ * The launch77 section within package.json
+ */
+interface PackageManifest {
+    installedPlugins?: Record<string, InstalledPluginMetadata>;
+    template?: TemplateReference;
+}
+/**
+ * Service responsible for package manifest operations.
+ * Handles reading and writing launch77 metadata in package.json files.
+ * The "package manifest" refers to the launch77 section within package.json.
+ */
+declare class PackageManifestService {
+    private filesystemService;
+    constructor(filesystemService?: FilesystemService);
+    /**
+     * Read the launch77 section (package manifest) from a package.json
+     */
+    readPackageManifest(packagePath: string): Promise<PackageManifest | null>;
+    /**
+     * Write the launch77 section (package manifest) to a package.json
+     */
+    writePackageManifest(packagePath: string, manifest: PackageManifest): Promise<void>;
+    /**
+     * Add an installed plugin to the manifest
+     */
+    addInstalledPlugin(packagePath: string, pluginKey: string, metadata: InstalledPluginMetadata): Promise<void>;
+    /**
+     * Remove an installed plugin from the manifest
+     */
+    removeInstalledPlugin(packagePath: string, pluginKey: string): Promise<void>;
+    /**
+     * Get installed plugins from the manifest
+     */
+    getInstalledPlugins(packagePath: string): Promise<Record<string, InstalledPluginMetadata>>;
+    /**
+     * Check if a plugin is installed
+     */
+    isPluginInstalled(packagePath: string, pluginKey: string): Promise<boolean>;
+    /**
+     * Get a specific installed plugin metadata
+     */
+    getInstalledPlugin(packagePath: string, pluginKey: string): Promise<InstalledPluginMetadata | null>;
+    /**
+     * Update package.json dependencies
+     */
+    addDependency(packagePath: string, packageName: string, version: string, isDev?: boolean): Promise<void>;
+    /**
+     * Remove a dependency from package.json
+     */
+    removeDependency(packagePath: string, packageName: string): Promise<void>;
+    /**
+     * Get the package.json content
+     */
+    readPackageJson(packagePath: string): Promise<unknown>;
+    /**
+     * Write the package.json content
+     */
+    writePackageJson(packagePath: string, packageJson: unknown): Promise<void>;
 }
 
 /**
- * Detect the Launch77 workspace context from the current working directory
- *
- * @param cwd - Current working directory path
- * @returns Context information about the workspace location
+ * Resolved plugin information for installation
  */
-declare function detectLaunch77Context(cwd: string): Promise<Launch77Context>;
+interface ResolvedPlugin {
+    name: string;
+    version: string;
+    path: string;
+    source: 'local' | 'npm';
+    metadata?: PluginMetadata;
+}
+/**
+ * Service responsible for plugin installation workflow.
+ * Handles generator execution, dependency management, and installation tracking.
+ */
+declare class PluginInstaller {
+    private filesystemService;
+    constructor(filesystemService?: FilesystemService);
+    /**
+     * Install a plugin into the target location
+     */
+    install(plugin: ResolvedPlugin, target: Target, targetPath: string, context: Launch77Context, logger?: (message: string) => void): Promise<void>;
+    /**
+     * Run a plugin's generator
+     */
+    runGenerator(plugin: ResolvedPlugin, _target: Target, targetPath: string, launch77Context: Launch77Context, logger?: (message: string) => void): Promise<void>;
+    /**
+     * Track plugin installation in package.json
+     */
+    trackInstallation(plugin: ResolvedPlugin, targetPath: string): Promise<void>;
+    /**
+     * Check if a plugin is already installed
+     */
+    isInstalled(pluginName: string, targetPath: string): Promise<boolean>;
+    /**
+     * Get installed plugin metadata
+     */
+    getInstalledPlugin(pluginName: string, targetPath: string): Promise<InstalledPluginMetadata | null>;
+    /**
+     * Uninstall a plugin
+     */
+    uninstall(pluginName: string, targetPath: string): Promise<void>;
+    /**
+     * Install npm dependencies
+     */
+    installDependencies(targetPath: string): Promise<void>;
+    /**
+     * Extract plugin key from package name
+     */
+    private extractPluginKey;
+}
 
 /**
- * Name Validation Utilities
- *
- * Provides validation for plugin names and npm package names.
- * Used by both CLI and plugin-runtime to ensure consistent naming rules.
+ * Result of downloading an npm package
  */
-interface ValidationResult$1 {
+interface DownloadPackageResult {
+    path: string;
+    version: string;
+    name: string;
+}
+/**
+ * Options for downloading an npm package
+ */
+interface DownloadPackageOptions {
+    packageName: string;
+}
+/**
+ * Validation result for npm package names
+ */
+interface ValidationResult {
     isValid: boolean;
     error?: string;
 }
 /**
- * Validate a plugin name
- *
- * Rules:
- * - Must start with a lowercase letter
- * - Can contain lowercase letters, numbers, and hyphens
- * - Cannot contain uppercase, spaces, underscores, or special characters
- *
- * @param name - The plugin name to validate
- * @returns ValidationResult indicating if valid and error message if not
- *
- * @example
- * validatePluginName('my-plugin') // { isValid: true }
- * validatePluginName('MyPlugin') // { isValid: false, error: '...' }
+ * Service responsible for NPM operations.
+ * Provides a clean abstraction over npm commands and package management.
  */
-declare function validatePluginName(name: string): ValidationResult$1;
+declare class NpmService {
+    /**
+     * Validate an npm package name (scoped or unscoped)
+     *
+     * Rules for unscoped packages:
+     * - Must start with a lowercase letter
+     * - Can contain lowercase letters, numbers, hyphens, periods, underscores
+     *
+     * Rules for scoped packages:
+     * - Format: @org/package
+     * - Both org and package follow npm naming rules
+     *
+     * @param name - The npm package name to validate
+     * @returns ValidationResult indicating if valid and error message if not
+     */
+    validatePackageName(name: string): ValidationResult;
+    /**
+     * Parse a package name input and determine its type
+     *
+     * Returns information about whether the input is:
+     * - A scoped npm package (e.g., @org/package)
+     * - An unscoped name (e.g., my-package)
+     * - Invalid
+     */
+    parsePackageName(name: string): {
+        type: 'scoped' | 'unscoped' | 'invalid';
+        isValid: boolean;
+        name?: string;
+        org?: string;
+        package?: string;
+        error?: string;
+    };
+    /**
+     * Install npm dependencies in a directory
+     */
+    install(cwd: string): Promise<void>;
+    /**
+     * Install npm dependencies with legacy peer deps flag
+     */
+    installWithLegacyPeerDeps(cwd: string): Promise<void>;
+    /**
+     * Download an npm package to a temporary directory
+     */
+    downloadPackage(options: DownloadPackageOptions): Promise<DownloadPackageResult>;
+    /**
+     * Get information about an npm package
+     */
+    getPackageInfo(packageName: string): Promise<unknown>;
+    /**
+     * Check if a package exists on npm
+     */
+    packageExists(packageName: string): Promise<boolean>;
+    /**
+     * Install a specific package as a dependency
+     */
+    installPackage(packageName: string, cwd: string, isDev?: boolean): Promise<void>;
+    /**
+     * Uninstall a package
+     */
+    uninstallPackage(packageName: string, cwd: string): Promise<void>;
+    /**
+     * Clean up a temporary download directory
+     */
+    cleanupDownload(downloadPath: string): Promise<void>;
+}
+
 /**
- * Validate an npm package name (scoped or unscoped)
- *
- * Rules for unscoped packages:
- * - Must start with a lowercase letter
- * - Can contain lowercase letters, numbers, and hyphens
- *
- * Rules for scoped packages:
- * - Format: @org/package
- * - Org must contain lowercase letters, numbers, and hyphens
- * - Package must contain lowercase letters, numbers, and hyphens
- *
- * @param name - The npm package name to validate
- * @returns ValidationResult indicating if valid and error message if not
- *
- * @example
- * isValidNpmPackageName('my-package') // { isValid: true }
- * isValidNpmPackageName('@org/my-package') // { isValid: true }
- * isValidNpmPackageName('@release') // { isValid: false, error: '...' }
+ * Base interface for package resolution results
  */
-declare function isValidNpmPackageName(name: string): ValidationResult$1;
+interface PackageResolution {
+    /** The source of the package */
+    source: 'local' | 'npm';
+    /** The resolved name/package to use */
+    resolvedName: string;
+    /** The local path if source is 'local' */
+    localPath?: string;
+    /** The npm package name if source is 'npm' */
+    npmPackage?: string;
+    /** The version from package.json (required for local packages, undefined for npm until installed) */
+    version?: string;
+}
 /**
- * Parse a plugin name input and determine its type
- *
- * Returns information about whether the input is:
- * - A scoped npm package (e.g., @org/package)
- * - An unscoped name (e.g., my-plugin)
- * - Invalid
+ * Abstract base class for resolving Launch77 packages
  *
- * @param name - The plugin name to parse
- * @returns Object with type and validation info
+ * Provides generic resolution logic for finding packages in:
+ * 1. Local workspace directory (e.g., plugins/, app-templates/)
+ * 2. npm packages with configured prefix (e.g., @launch77-shared/plugin-*, @launch77-shared/app-template-*)
  *
- * @example
- * parsePluginName('release')
- * // { type: 'unscoped', isValid: true, name: 'release' }
- *
- * parsePluginName('@ibm/analytics')
- * // { type: 'scoped', isValid: true, name: '@ibm/analytics', org: 'ibm', package: 'analytics' }
+ * Concrete implementations must provide:
+ * - Folder name for local resolution
+ * - Package prefix for npm resolution
+ * - Verification logic to validate local packages
+ */
+declare abstract class PackageResolver {
+    protected npmService: NpmService;
+    constructor();
+    /**
+     * Get the local folder name where packages of this type are stored
+     * @example 'plugins' or 'app-templates'
+     */
+    protected abstract getFolderName(): string;
+    /**
+     * Get the npm package prefix for unscoped packages
+     * @example '@launch77-shared/plugin-' or '@launch77-shared/app-template-'
+     */
+    protected abstract getPackagePrefix(): string;
+    /**
+     * Verify that a local package is valid and complete
+     * @param localPath - The local directory path to verify
+     * @returns true if the package is valid, false otherwise
+     */
+    protected abstract verify(localPath: string): Promise<boolean>;
+    /**
+     * Validate package input name
+     *
+     * Accepts:
+     * - Unscoped names (e.g., "release", "my-package")
+     * - Scoped npm packages (e.g., "@ibm/package-name")
+     *
+     * Rejects:
+     * - Invalid formats
+     * - Empty strings
+     * - Names with invalid characters
+     *
+     * @param name - The package name to validate
+     * @returns ValidationResult with isValid and optional error message
+     *
+     * @example
+     * validateInput('release') // { isValid: true }
+     * validateInput('@ibm/analytics') // { isValid: true }
+     * validateInput('@invalid') // { isValid: false, error: '...' }
+     */
+    validateInput(name: string): ValidationResult;
+    /**
+     * Convert an unscoped package name to an npm package name
+     *
+     * Rules:
+     * - Unscoped names: prefix with configured package prefix
+     * - Scoped names: use as-is
+     *
+     * @param name - The package name (must be validated first)
+     * @returns The npm package name
+     *
+     * @example
+     * toNpmPackageName('release') // '@launch77-shared/plugin-release' (for PluginResolver)
+     * toNpmPackageName('@ibm/analytics') // '@ibm/analytics'
+     */
+    toNpmPackageName(name: string): string;
+    /**
+     * Read version from package.json
+     * @param packagePath - The path to the package directory
+     * @returns The version string from package.json
+     * @throws If package.json doesn't exist, can't be read, or is missing the version field
+     */
+    private readVersion;
+    /**
+     * Resolve package location from name
+     *
+     * Resolution order:
+     * 1. Check local workspace directory (configured by getFolderName())
+     * 2. Verify local package is valid (using verify())
+     * 3. Fall back to npm package name (with configured prefix)
+     * 4. Read version from package.json (if available)
+     *
+     * @param name - The package name to resolve
+     * @param workspaceRoot - The workspace root directory
+     * @returns PackageResolution with source, resolved location, and version
+     *
+     * @example
+     * // Local package found
+     * await resolveLocation('my-package', '/workspace')
+     * // { source: 'local', resolvedName: 'my-package', localPath: '/workspace/plugins/my-package', version: '1.0.0' }
+     *
+     * // Not found locally, resolve to npm
+     * await resolveLocation('release', '/workspace')
+     * // { source: 'npm', resolvedName: 'release', npmPackage: '@launch77-shared/plugin-release' }
+     *
+     * // Scoped package always resolves to npm
+     * await resolveLocation('@ibm/analytics', '/workspace')
+     * // { source: 'npm', resolvedName: '@ibm/analytics', npmPackage: '@ibm/analytics' }
+     */
+    resolveLocation(name: string, workspaceRoot: string): Promise<PackageResolution>;
+}
+
+/**
+ * Plugin resolver implementation
  *
- * parsePluginName('@release')
- * // { type: 'invalid', isValid: false, error: '...' }
+ * Resolves plugins from:
+ * - Local workspace plugins/ directory
+ * - npm packages with @launch77-shared/plugin- prefix
  */
-declare function parsePluginName(name: string): {
-    type: 'scoped' | 'unscoped' | 'invalid';
-    isValid: boolean;
-    name?: string;
-    org?: string;
-    package?: string;
-    error?: string;
-};
+declare class PluginResolver extends PackageResolver {
+    protected getFolderName(): string;
+    protected getPackagePrefix(): string;
+    protected verify(localPath: string): Promise<boolean>;
+}
 
-interface PluginConsistencyError {
-    library: string;
-    packageJsonVersion: string;
-    pluginJsonVersion: string;
+declare class PluginNotFoundError extends Error {
+    constructor(pluginName: string);
 }
-interface ValidationResult {
-    valid: boolean;
-    errors: PluginConsistencyError[];
+declare class InvalidPluginContextError extends Error {
+    constructor(message: string);
 }
 /**
- * Validate that library versions in plugin.json match those in package.json
- *
- * This ensures that plugin templates (which use package.json versions during development)
- * install the same library versions for end users (which use plugin.json versions).
- *
- * @param pluginPath - Absolute path to the plugin directory
- * @returns Validation result with any errors found
- * @throws Error if package.json or plugin.json cannot be read
+ * Factory function to create standardized InvalidPluginContextError
+ * for when plugin:install is run outside of a package directory
  */
-declare function validatePluginConsistency(pluginPath: string): Promise<ValidationResult>;
+declare function createInvalidContextError(currentLocation: string): InvalidPluginContextError;
+/**
+ * Error when plugin.json is missing the required 'targets' field
+ */
+declare class MissingPluginTargetsError extends Error {
+    constructor(pluginName: string);
+}
 /**
- * Validate plugin consistency and throw a formatted error if validation fails
+ * Factory function to create error when plugin targets don't match current location
+ */
+declare function createInvalidTargetError(pluginName: string, currentTarget: string, allowedTargets: string[]): InvalidPluginContextError;
+declare class PluginInstallationError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error when plugin resolution fails
+ */
+declare class PluginResolutionError extends Error {
+    constructor(pluginName: string, reason: string);
+}
+/**
+ * Error when npm package installation fails
+ */
+declare class NpmInstallationError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(packageName: string, cause?: Error | undefined);
+}
+/**
+ * Error when plugin directory is not found for deletion
+ */
+declare class PluginDirectoryNotFoundError extends Error {
+    constructor(pluginName: string, expectedPath: string);
+}
+/**
+ * Error when plugin name validation fails
+ */
+declare class InvalidPluginNameError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Options for downloading an npm package
+ */
+interface DownloadNpmPackageOptions {
+    /** The npm package name to download */
+    packageName: string;
+    /** The workspace root directory where node_modules will be */
+    workspaceRoot: string;
+    /** Optional logger function for status messages */
+    logger?: (message: string) => void;
+}
+/**
+ * Result of downloading an npm package
+ */
+interface DownloadNpmPackageResult {
+    /** Full path to the downloaded package in node_modules */
+    packagePath: string;
+    /** The package name that was downloaded */
+    packageName: string;
+}
+/**
+ * Download and install an npm package to workspace node_modules
  *
- * This is a convenience function for use in build scripts that should
- * fail fast with a clear error message.
+ * This function:
+ * - Runs `npm install {packageName} --save-dev` in the workspace root
+ * - Adds the package to workspace package.json devDependencies
+ * - Returns the path to the installed package in node_modules
  *
- * @param pluginPath - Absolute path to the plugin directory
- * @throws Error with formatted message if validation fails
+ * @param options - Download options
+ * @returns The path to the installed package
+ * @throws NpmInstallationError if the download fails
+ *
+ * @example
+ * const result = await downloadNpmPackage({
+ *   packageName: '@launch77-shared/plugin-release',
+ *   workspaceRoot: '/path/to/workspace',
+ *   logger: (msg) => console.log(msg)
+ * })
+ * // result.packagePath: '/path/to/workspace/node_modules/@launch77-shared/plugin-release'
  */
-declare function validatePluginConsistencyOrThrow(pluginPath: string): Promise<void>;
+declare function downloadNpmPackage(options: DownloadNpmPackageOptions): Promise<DownloadNpmPackageResult>;
 
-export { Generator, type GeneratorContext, type InstalledPluginMetadata, type Launch77Context, type Launch77LocationType, type Launch77PackageManifest, type PluginConsistencyError, type PluginMetadata, type ValidationResult as PluginValidationResult, StandardGenerator, type TemplateMetadata, type TemplateReference, type ValidationResult$1 as ValidationResult, copyRecursive, detectLaunch77Context, isValidNpmPackageName, parsePluginName, pathExists, readPluginMetadata, readTemplateMetadata, validatePluginConsistency, validatePluginConsistencyOrThrow, validatePluginName };
+export { type DeletePluginRequest, type DeletePluginResult, type DownloadNpmPackageOptions, type DownloadNpmPackageResult, type DownloadPackageResult, FilesystemService, Generator, type GeneratorContext, type HookResult, type InstallPluginRequest, type InstallPluginResult, type InstalledPluginMetadata, InvalidPluginContextError, InvalidPluginNameError, type Launch77Context, type Launch77LocationType, MetadataService, MissingPluginTargetsError, NpmInstallationError, NpmService, type PackageManifest, PackageManifestService, type PackageResolution, PackageResolver, type ParsedLocation, type PluginConsistencyError, PluginDirectoryNotFoundError, PluginInstallationError, PluginInstaller, type PluginMetadata, PluginNotFoundError, PluginResolutionError, PluginResolver, PluginService, type ValidationResult$1 as PluginValidationResult, StandardGenerator, type Target, type TemplateMetadata, type TemplateReference, type ValidationResult$2 as ValidationResult, type WorkspaceManifest, WorkspaceManifestService, WorkspaceService, createInvalidContextError, createInvalidTargetError, detectLaunch77Context, downloadNpmPackage, parseLocationFromPath };