@launch77/cli 1.3.0 → 1.4.1

package/src/modules/plugin/lib/plugin-resolver.ts

@@ -0,0 +1,160 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+import { parsePluginName, isValidNpmPackageName } from '@launch77/plugin-runtime'
+
+import type { ValidationResult } from '@launch77/plugin-runtime'
+
+/**
+ * Plugin resolution result
+ */
+export interface PluginResolution {
+  /** The source of the plugin */
+  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
+}
+
+/**
+ * Validate plugin input name
+ *
+ * Accepts:
+ * - Unscoped names (e.g., "release", "my-plugin")
+ * - Scoped npm packages (e.g., "@ibm/plugin-name")
+ *
+ * Rejects:
+ * - Invalid formats
+ * - Empty strings
+ * - Names with invalid characters
+ *
+ * @param name - The plugin name to validate
+ * @returns ValidationResult with isValid and optional error message
+ *
+ * @example
+ * validatePluginInput('release') // { isValid: true }
+ * validatePluginInput('@ibm/analytics') // { isValid: true }
+ * validatePluginInput('@invalid') // { isValid: false, error: '...' }
+ */
+export function validatePluginInput(name: string): ValidationResult {
+  if (!name || name.trim().length === 0) {
+    return {
+      isValid: false,
+      error: 'Plugin name cannot be empty',
+    }
+  }
+
+  const trimmedName = name.trim()
+
+  // Parse the name to determine type and validate
+  const parsed = parsePluginName(trimmedName)
+
+  if (!parsed.isValid) {
+    return {
+      isValid: false,
+      error: parsed.error,
+    }
+  }
+
+  // If it's scoped, it must be a valid npm package name
+  if (parsed.type === 'scoped') {
+    return isValidNpmPackageName(trimmedName)
+  }
+
+  // Unscoped names are valid for both local and npm
+  return { isValid: true }
+}
+
+/**
+ * Convert an unscoped plugin name to an npm package name
+ *
+ * Rules:
+ * - Unscoped names: prefix with @launch77-shared/plugin-
+ * - Scoped names: use as-is
+ *
+ * @param name - The plugin name (must be validated first)
+ * @returns The npm package name
+ *
+ * @example
+ * toNpmPackageName('release') // '@launch77-shared/plugin-release'
+ * toNpmPackageName('@ibm/analytics') // '@ibm/analytics'
+ */
+export function toNpmPackageName(name: string): string {
+  const trimmedName = name.trim()
+
+  // If already scoped, use as-is
+  if (trimmedName.startsWith('@')) {
+    return trimmedName
+  }
+
+  // Otherwise, convert to @launch77-shared/plugin-<name>
+  return `@launch77-shared/plugin-${trimmedName}`
+}
+
+/**
+ * Resolve plugin location from name
+ *
+ * Resolution order:
+ * 1. Check local workspace plugins directory
+ * 2. Resolve to npm package name
+ *
+ * @param name - The plugin name to resolve
+ * @param workspaceRoot - The workspace root directory
+ * @returns PluginResolution with source and resolved location
+ *
+ * @example
+ * // Local plugin found
+ * await resolvePluginLocation('my-plugin', '/workspace')
+ * // { source: 'local', resolvedName: 'my-plugin', localPath: '/workspace/plugins/my-plugin' }
+ *
+ * // Not found locally, resolve to npm
+ * await resolvePluginLocation('release', '/workspace')
+ * // { source: 'npm', resolvedName: 'release', npmPackage: '@launch77-shared/plugin-release' }
+ *
+ * // Scoped package always resolves to npm
+ * await resolvePluginLocation('@ibm/analytics', '/workspace')
+ * // { source: 'npm', resolvedName: '@ibm/analytics', npmPackage: '@ibm/analytics' }
+ */
+export async function resolvePluginLocation(name: string, workspaceRoot: string): Promise<PluginResolution> {
+  const trimmedName = name.trim()
+  const parsed = parsePluginName(trimmedName)
+
+  // If scoped, always use npm (local plugins are never scoped)
+  if (parsed.type === 'scoped') {
+    return {
+      source: 'npm',
+      resolvedName: trimmedName,
+      npmPackage: trimmedName,
+    }
+  }
+
+  // Check local workspace plugins directory
+  const localPath = path.join(workspaceRoot, 'plugins', trimmedName)
+  const localExists = await fs.pathExists(localPath)
+
+  if (localExists) {
+    // Verify it's a valid plugin (has plugin.json and dist/generator.js)
+    const hasPluginJson = await fs.pathExists(path.join(localPath, 'plugin.json'))
+    const hasGenerator = await fs.pathExists(path.join(localPath, 'dist/generator.js'))
+
+    if (hasPluginJson && hasGenerator) {
+      return {
+        source: 'local',
+        resolvedName: trimmedName,
+        localPath,
+      }
+    }
+  }
+
+  // Not found locally, resolve to npm package
+  const npmPackage = toNpmPackageName(trimmedName)
+
+  return {
+    source: 'npm',
+    resolvedName: trimmedName,
+    npmPackage,
+  }
+}

package/src/modules/plugin/services/plugin-create-service.ts

@@ -0,0 +1,69 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+
+import { validatePluginName } from '@launch77/plugin-runtime'
+import { processTemplate, getPluginTemplatePath } from '../../../infrastructure/template.js'
+import { toPascalCase } from '../../../utils/string.js'
+
+import type { Launch77Context } from '@launch77/plugin-runtime'
+
+export interface CreatePluginRequest {
+  pluginName: string
+  description?: string
+}
+
+export interface CreatePluginResult {
+  pluginName: string
+  pluginPath: string
+}
+
+export class PluginCreateService {
+  /**
+   * Create a new plugin from template
+   */
+  async createPlugin(request: CreatePluginRequest, context: Launch77Context): Promise<CreatePluginResult> {
+    const { pluginName, description } = request
+
+    // 1. Validate plugin name
+    const nameValidation = validatePluginName(pluginName)
+    if (!nameValidation.isValid) {
+      throw new Error(nameValidation.error || 'Invalid plugin name')
+    }
+
+    // 2. Validate workspace context
+    if (!context.isValid) {
+      throw new Error('Must be run from within a Launch77 workspace')
+    }
+
+    // 3. Determine plugin path
+    const pluginPath = path.join(context.workspaceRoot, 'plugins', pluginName)
+
+    // 4. Check if plugin already exists
+    if (await fs.pathExists(pluginPath)) {
+      throw new Error(`Plugin '${pluginName}' already exists at ${pluginPath}`)
+    }
+
+    // 5. Get plugin template path
+    const templatePath = getPluginTemplatePath('plugin')
+
+    // 6. Check if template exists
+    if (!(await fs.pathExists(templatePath))) {
+      throw new Error(`Plugin template not found at ${templatePath}`)
+    }
+
+    // 7. Process template with context
+    await processTemplate(templatePath, pluginPath, {
+      appName: pluginName, // Required by TemplateContext but not used for plugin templates
+      pluginName,
+      pluginNamePascal: toPascalCase(pluginName),
+      workspaceName: context.workspaceName,
+      description: description || `Launch77 plugin for ${pluginName}`,
+    })
+
+    return {
+      pluginName,
+      pluginPath,
+    }
+  }
+}

package/src/modules/plugin/services/plugin-svc.test.ts

@@ -0,0 +1,418 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest'
+import * as path from 'path'
+import * as os from 'os'
+import fs from 'fs-extra'
+import { PluginService } from './plugin-svc.js'
+import type { Launch77Context } from '@launch77/plugin-runtime'
+
+describe('PluginService', () => {
+  let tempDir: string
+  let service: PluginService
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'plugin-svc-test-'))
+    service = new PluginService()
+  })
+
+  afterEach(async () => {
+    await fs.remove(tempDir)
+  })
+
+  describe('validateContext', () => {
+    // Valid contexts - test return values
+    test('should return "app" for workspace-app location', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-app',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-app',
+        appName: 'test-app',
+      }
+
+      const result = (service as any).validateContext(context)
+      expect(result).toBe('app')
+    })
+
+    test('should return "library" for workspace-library location', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-library',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-library',
+        appName: 'test-library',
+      }
+
+      const result = (service as any).validateContext(context)
+      expect(result).toBe('library')
+    })
+
+    test('should return "plugin" for workspace-plugin location', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-plugin',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-plugin',
+        appName: 'test-plugin',
+      }
+
+      const result = (service as any).validateContext(context)
+      expect(result).toBe('plugin')
+    })
+
+    test('should return "app-template" for workspace-app-template location', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-app-template',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-template',
+        appName: 'test-template',
+      }
+
+      const result = (service as any).validateContext(context)
+      expect(result).toBe('app-template')
+    })
+
+    // Invalid contexts - test exact error messages
+    test('should throw InvalidPluginContextError for workspace-root', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-root',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'workspace',
+        appName: undefined,
+      }
+
+      expect(() => (service as any).validateContext(context)).toThrow('plugin:install must be run from within a package directory.')
+    })
+
+    test('should throw InvalidPluginContextError for non-workspace', () => {
+      const context = {
+        isValid: false,
+        locationType: 'non-workspace' as const,
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'unknown',
+        appName: undefined,
+      }
+
+      expect(() => (service as any).validateContext(context)).toThrow('plugin:install must be run from within a package directory.')
+    })
+
+    test('should throw InvalidPluginContextError when appName is missing', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-app',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-app',
+        appName: undefined,
+      }
+
+      expect(() => (service as any).validateContext(context)).toThrow('Could not determine package name. This is a bug. Please report it.')
+    })
+
+    test('should throw InvalidPluginContextError when appName is empty string', () => {
+      const context: Launch77Context = {
+        isValid: true,
+        locationType: 'workspace-app',
+        workspaceRoot: tempDir,
+        workspaceName: 'test-workspace',
+        workspaceVersion: '1.0.0',
+        appsDir: path.join(tempDir, 'apps'),
+        packageName: 'test-app',
+        appName: '',
+      }
+
+      expect(() => (service as any).validateContext(context)).toThrow('Could not determine package name. This is a bug. Please report it.')
+    })
+  })
+
+  describe('validatePluginTargets', () => {
+    // Valid scenarios - verify metadata returned
+    test('should return metadata when plugin targets current package type', async () => {
+      const pluginDir = path.join(tempDir, 'test-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'test-plugin',
+        version: '1.0.0',
+        targets: ['app', 'library'],
+      })
+
+      const result = await (service as any).validatePluginTargets(pluginDir, 'test-plugin', 'app')
+      expect(result).toEqual({
+        name: 'test-plugin',
+        version: '1.0.0',
+        targets: ['app', 'library'],
+      })
+    })
+
+    test('should accept plugin with multiple targets including current', async () => {
+      const pluginDir = path.join(tempDir, 'multi-target-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'multi-target-plugin',
+        version: '2.0.0',
+        targets: ['app', 'library', 'plugin', 'app-template'],
+      })
+
+      const result = await (service as any).validatePluginTargets(pluginDir, 'multi-target-plugin', 'library')
+      expect(result.targets).toContain('library')
+      expect(result.targets).toHaveLength(4)
+    })
+
+    test('should handle plugin.json with optional fields (pluginDependencies, libraryDependencies)', async () => {
+      const pluginDir = path.join(tempDir, 'full-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'full-plugin',
+        version: '1.5.0',
+        targets: ['app'],
+        pluginDependencies: { 'other-plugin': '^1.0.0' },
+        libraryDependencies: { react: '^18.0.0' },
+      })
+
+      const result = await (service as any).validatePluginTargets(pluginDir, 'full-plugin', 'app')
+      expect(result.pluginDependencies).toEqual({ 'other-plugin': '^1.0.0' })
+      expect(result.libraryDependencies).toEqual({ react: '^18.0.0' })
+    })
+
+    // Error scenarios - test exact error messages
+    test('should throw MissingPluginTargetsError when targets is undefined', async () => {
+      const pluginDir = path.join(tempDir, 'no-targets-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'no-targets-plugin',
+        version: '1.0.0',
+      })
+
+      await expect((service as any).validatePluginTargets(pluginDir, 'no-targets-plugin', 'app')).rejects.toThrow("Plugin 'no-targets-plugin' is missing the required 'targets' field in plugin.json.")
+    })
+
+    test('should throw MissingPluginTargetsError when targets is empty array', async () => {
+      const pluginDir = path.join(tempDir, 'empty-targets-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'empty-targets-plugin',
+        version: '1.0.0',
+        targets: [],
+      })
+
+      await expect((service as any).validatePluginTargets(pluginDir, 'empty-targets-plugin', 'app')).rejects.toThrow("Plugin 'empty-targets-plugin' is missing the required 'targets' field in plugin.json.")
+    })
+
+    test('should throw error when targets does not include current target', async () => {
+      const pluginDir = path.join(tempDir, 'incompatible-plugin')
+      await fs.ensureDir(pluginDir)
+      await fs.writeJson(path.join(pluginDir, 'plugin.json'), {
+        name: 'incompatible-plugin',
+        version: '1.0.0',
+        targets: ['library', 'plugin'],
+      })
+
+      await expect((service as any).validatePluginTargets(pluginDir, 'incompatible-plugin', 'app')).rejects.toThrow("Plugin 'incompatible-plugin' cannot be installed in a 'app' package.")
+    })
+
+    test('should handle missing plugin.json file gracefully', async () => {
+      const pluginDir = path.join(tempDir, 'no-plugin-json')
+      await fs.ensureDir(pluginDir)
+
+      await expect((service as any).validatePluginTargets(pluginDir, 'no-plugin-json', 'app')).rejects.toThrow()
+    })
+  })
+
+  describe('checkExistingInstallation', () => {
+    const mockLogger = (message: string) => {
+      /* capture logs */
+    }
+
+    // Not installed - return null
+    test('should return null when plugin is not installed', async () => {
+      const packageDir = path.join(tempDir, 'app1')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app1',
+        version: '1.0.0',
+        launch77: {
+          installedPlugins: {},
+        },
+      })
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    test('should return null when package.json does not exist', async () => {
+      const packageDir = path.join(tempDir, 'nonexistent')
+      await fs.ensureDir(packageDir)
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    test('should return null when launch77 field is missing', async () => {
+      const packageDir = path.join(tempDir, 'app2')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app2',
+        version: '1.0.0',
+      })
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    test('should return null when installedPlugins is missing', async () => {
+      const packageDir = path.join(tempDir, 'app3')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app3',
+        version: '1.0.0',
+        launch77: {},
+      })
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    test('should return null when installedPlugins exists but plugin not in it', async () => {
+      const packageDir = path.join(tempDir, 'app4')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app4',
+        version: '1.0.0',
+        launch77: {
+          installedPlugins: {
+            'other-plugin': {
+              package: 'other-plugin',
+              version: '1.0.0',
+              installedAt: '2024-01-01T00:00:00.000Z',
+              source: 'local',
+            },
+          },
+        },
+      })
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    // Already installed - return result object
+    test('should return early-exit result with correct structure when plugin is installed', async () => {
+      const packageDir = path.join(tempDir, 'app5')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app5',
+        version: '1.0.0',
+        launch77: {
+          installedPlugins: {
+            'test-plugin': {
+              package: 'test-plugin',
+              version: '1.5.0',
+              installedAt: '2024-01-15T10:30:00.000Z',
+              source: 'local',
+            },
+          },
+        },
+      })
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toEqual({
+        pluginName: 'test-plugin',
+        filesInstalled: false,
+        packageJsonUpdated: false,
+        dependenciesInstalled: false,
+      })
+    })
+
+    test('should log correct message for local plugin (package name matches plugin name)', async () => {
+      const packageDir = path.join(tempDir, 'app6')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app6',
+        version: '1.0.0',
+        launch77: {
+          installedPlugins: {
+            release: {
+              package: 'release',
+              version: '2.0.0',
+              installedAt: '2024-02-01T12:00:00.000Z',
+              source: 'local',
+            },
+          },
+        },
+      })
+
+      const logs: string[] = []
+      const captureLogger = (message: string) => logs.push(message)
+
+      const result = await (service as any).checkExistingInstallation('release', packageDir, captureLogger)
+      expect(result).not.toBeNull()
+      expect(logs.some((log) => log.includes("Plugin 'release' is already installed"))).toBe(true)
+      expect(logs.some((log) => log.includes('release') && log.includes('local'))).toBe(true)
+    })
+
+    test('should log correct message for npm plugin (package name is scoped)', async () => {
+      const packageDir = path.join(tempDir, 'app7')
+      await fs.ensureDir(packageDir)
+      await fs.writeJson(path.join(packageDir, 'package.json'), {
+        name: 'app7',
+        version: '1.0.0',
+        launch77: {
+          installedPlugins: {
+            analytics: {
+              package: '@myorg/analytics-plugin',
+              version: '3.1.0',
+              installedAt: '2024-03-01T15:45:00.000Z',
+              source: 'npm',
+            },
+          },
+        },
+      })
+
+      const logs: string[] = []
+      const captureLogger = (message: string) => logs.push(message)
+
+      const result = await (service as any).checkExistingInstallation('analytics', packageDir, captureLogger)
+      expect(result).not.toBeNull()
+      expect(logs.some((log) => log.includes("Plugin 'analytics' is already installed"))).toBe(true)
+      expect(logs.some((log) => log.includes('@myorg/analytics-plugin') && log.includes('npm'))).toBe(true)
+    })
+
+    // Edge cases
+    test('should handle malformed package.json gracefully (invalid JSON)', async () => {
+      const packageDir = path.join(tempDir, 'app8')
+      await fs.ensureDir(packageDir)
+      await fs.writeFile(path.join(packageDir, 'package.json'), '{ invalid json }')
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+
+    test('should handle package.json read errors (permissions, etc.)', async () => {
+      const packageDir = path.join(tempDir, 'app9')
+      // Don't create the directory - simulate permission/access error
+
+      const result = await (service as any).checkExistingInstallation('test-plugin', packageDir, mockLogger)
+      expect(result).toBeNull()
+    })
+  })
+})