@launch77/cli 1.4.3 → 1.5.0

package/src/infrastructure/package-resolver.test.ts

@@ -0,0 +1,313 @@
+import * as os from 'os'
+import * as path from 'path'
+
+import fs from 'fs-extra'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+
+import { PackageResolver } from './package-resolver.js'
+
+/**
+ * Test implementation of PackageResolver for unit testing
+ */
+class TestPackageResolver extends PackageResolver {
+  protected getFolderName(): string {
+    return 'test-packages'
+  }
+
+  protected getPackagePrefix(): string {
+    return '@test-org/test-'
+  }
+
+  protected async verify(localPath: string): Promise<boolean> {
+    // Verify by checking for package.json
+    const packageJsonPath = path.join(localPath, 'package.json')
+    return await fs.pathExists(packageJsonPath)
+  }
+}
+
+describe('PackageResolver', () => {
+  let resolver: TestPackageResolver
+  let tempDir: string
+
+  beforeEach(async () => {
+    resolver = new TestPackageResolver()
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'package-resolver-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.remove(tempDir)
+  })
+
+  describe('validateInput', () => {
+    describe('valid inputs', () => {
+      it('should accept valid unscoped package names', () => {
+        const result = resolver.validateInput('release')
+        expect(result.isValid).toBe(true)
+        expect(result.error).toBeUndefined()
+      })
+
+      it('should accept unscoped names with hyphens', () => {
+        const result = resolver.validateInput('my-package')
+        expect(result.isValid).toBe(true)
+      })
+
+      it('should accept unscoped names with numbers', () => {
+        const result = resolver.validateInput('package-123')
+        expect(result.isValid).toBe(true)
+      })
+
+      it('should accept valid scoped packages', () => {
+        const result = resolver.validateInput('@ibm/analytics')
+        expect(result.isValid).toBe(true)
+        expect(result.error).toBeUndefined()
+      })
+
+      it('should accept scoped packages with hyphens', () => {
+        const result = resolver.validateInput('@launch77-shared/plugin-release')
+        expect(result.isValid).toBe(true)
+      })
+
+      it('should trim whitespace from valid names', () => {
+        const result = resolver.validateInput('  release  ')
+        expect(result.isValid).toBe(true)
+      })
+
+      it('should trim whitespace from scoped names', () => {
+        const result = resolver.validateInput('  @ibm/analytics  ')
+        expect(result.isValid).toBe(true)
+      })
+    })
+
+    describe('invalid inputs', () => {
+      it('should reject empty string', () => {
+        const result = resolver.validateInput('')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBe('Package name cannot be empty')
+      })
+
+      it('should reject whitespace-only string', () => {
+        const result = resolver.validateInput('   ')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBe('Package name cannot be empty')
+      })
+
+      it('should reject invalid scoped package without name', () => {
+        const result = resolver.validateInput('@invalid')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toContain('Scoped package must be in format @org/package')
+      })
+
+      it('should reject invalid scoped package without scope', () => {
+        const result = resolver.validateInput('@/package')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBeDefined()
+      })
+
+      it('should reject invalid scoped package with missing name after slash', () => {
+        const result = resolver.validateInput('@org/')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toContain('Scoped package must be in format @org/package')
+      })
+
+      it('should reject names with uppercase letters', () => {
+        const result = resolver.validateInput('MyPackage')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBeDefined()
+      })
+
+      it('should reject names starting with numbers', () => {
+        const result = resolver.validateInput('123package')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBeDefined()
+      })
+
+      it('should reject names with underscores', () => {
+        const result = resolver.validateInput('my_package')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBeDefined()
+      })
+
+      it('should reject names with spaces', () => {
+        const result = resolver.validateInput('my package')
+        expect(result.isValid).toBe(false)
+        expect(result.error).toBeDefined()
+      })
+    })
+  })
+
+  describe('toNpmPackageName', () => {
+    describe('unscoped names', () => {
+      it('should prefix unscoped package names', () => {
+        const result = resolver.toNpmPackageName('release')
+        expect(result).toBe('@test-org/test-release')
+      })
+
+      it('should prefix unscoped names with hyphens', () => {
+        const result = resolver.toNpmPackageName('my-package')
+        expect(result).toBe('@test-org/test-my-package')
+      })
+
+      it('should trim whitespace from unscoped names', () => {
+        const result = resolver.toNpmPackageName('  release  ')
+        expect(result).toBe('@test-org/test-release')
+      })
+    })
+
+    describe('scoped names', () => {
+      it('should return scoped packages as-is', () => {
+        const result = resolver.toNpmPackageName('@ibm/analytics')
+        expect(result).toBe('@ibm/analytics')
+      })
+
+      it('should return scoped packages with hyphens as-is', () => {
+        const result = resolver.toNpmPackageName('@launch77-shared/plugin-release')
+        expect(result).toBe('@launch77-shared/plugin-release')
+      })
+
+      it('should trim whitespace from scoped names', () => {
+        const result = resolver.toNpmPackageName('  @ibm/analytics  ')
+        expect(result).toBe('@ibm/analytics')
+      })
+    })
+  })
+
+  describe('resolveLocation', () => {
+    describe('local resolution (unscoped names)', () => {
+      it('should resolve to local when valid package exists', async () => {
+        const packageName = 'my-local-package'
+        const localPath = path.join(tempDir, 'test-packages', packageName)
+        await fs.ensureDir(localPath)
+        await fs.writeJSON(path.join(localPath, 'package.json'), { name: packageName, version: '0.0.1' })
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('local')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.localPath).toBe(localPath)
+        expect(result.npmPackage).toBeUndefined()
+      })
+
+      it('should fall back to npm when local directory exists but is invalid', async () => {
+        const packageName = 'invalid-local-package'
+        const localPath = path.join(tempDir, 'test-packages', packageName)
+        await fs.ensureDir(localPath)
+        // Don't create package.json, making it invalid
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe('@test-org/test-invalid-local-package')
+        expect(result.localPath).toBeUndefined()
+      })
+
+      it('should fall back to npm when local directory does not exist', async () => {
+        const packageName = 'nonexistent-package'
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe('@test-org/test-nonexistent-package')
+        expect(result.localPath).toBeUndefined()
+      })
+
+      it('should trim whitespace from package names', async () => {
+        const packageName = 'my-package'
+        const localPath = path.join(tempDir, 'test-packages', packageName)
+        await fs.ensureDir(localPath)
+        await fs.writeJSON(path.join(localPath, 'package.json'), { name: packageName, version: '0.0.1' })
+
+        const result = await resolver.resolveLocation('  my-package  ', tempDir)
+
+        expect(result.source).toBe('local')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.localPath).toBe(localPath)
+      })
+    })
+
+    describe('npm resolution (scoped names)', () => {
+      it('should always resolve scoped packages to npm', async () => {
+        const packageName = '@ibm/analytics'
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe(packageName)
+        expect(result.localPath).toBeUndefined()
+      })
+
+      it('should resolve scoped packages to npm even if local directory exists', async () => {
+        const packageName = '@ibm/analytics'
+        // Create a local directory with the scoped package name (edge case)
+        const localPath = path.join(tempDir, 'test-packages', '@ibm/analytics')
+        await fs.ensureDir(localPath)
+        await fs.writeJSON(path.join(localPath, 'package.json'), { name: packageName })
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe(packageName)
+        expect(result.localPath).toBeUndefined()
+      })
+
+      it('should handle scoped packages with hyphens', async () => {
+        const packageName = '@launch77-shared/plugin-release'
+
+        const result = await resolver.resolveLocation(packageName, tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe(packageName)
+      })
+
+      it('should trim whitespace from scoped package names', async () => {
+        const packageName = '@ibm/analytics'
+
+        const result = await resolver.resolveLocation('  @ibm/analytics  ', tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe(packageName)
+        expect(result.npmPackage).toBe(packageName)
+      })
+    })
+
+    describe('edge cases', () => {
+      it('should handle empty workspace test-packages directory', async () => {
+        // Ensure the directory exists but is empty
+        await fs.ensureDir(path.join(tempDir, 'test-packages'))
+
+        const result = await resolver.resolveLocation('some-package', tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe('some-package')
+        expect(result.npmPackage).toBe('@test-org/test-some-package')
+      })
+
+      it('should handle missing workspace test-packages directory', async () => {
+        // Don't create the test-packages directory at all
+
+        const result = await resolver.resolveLocation('some-package', tempDir)
+
+        expect(result.source).toBe('npm')
+        expect(result.resolvedName).toBe('some-package')
+        expect(result.npmPackage).toBe('@test-org/test-some-package')
+      })
+
+      it('should handle different workspace root paths', async () => {
+        const customRoot = path.join(tempDir, 'custom', 'workspace')
+        const packageName = 'my-package'
+        const localPath = path.join(customRoot, 'test-packages', packageName)
+        await fs.ensureDir(localPath)
+        await fs.writeJSON(path.join(localPath, 'package.json'), { name: packageName, version: '0.0.1' })
+
+        const result = await resolver.resolveLocation(packageName, customRoot)
+
+        expect(result.source).toBe('local')
+        expect(result.localPath).toBe(localPath)
+      })
+    })
+  })
+})

package/src/infrastructure/package-resolver.ts

@@ -0,0 +1,223 @@
+import * as path from 'path'
+
+import { parsePluginName, isValidNpmPackageName } from '@launch77/plugin-runtime'
+import fs from 'fs-extra'
+
+import type { ValidationResult } from '@launch77/plugin-runtime'
+
+/**
+ * Base interface for package resolution results
+ */
+export 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
+}
+
+/**
+ * Abstract base class for resolving Launch77 packages
+ *
+ * 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-*)
+ *
+ * Concrete implementations must provide:
+ * - Folder name for local resolution
+ * - Package prefix for npm resolution
+ * - Verification logic to validate local packages
+ */
+export abstract class PackageResolver {
+  /**
+   * 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 {
+    if (!name || name.trim().length === 0) {
+      return {
+        isValid: false,
+        error: 'Package name cannot be empty',
+      }
+    }
+
+    const trimmedName = name.trim()
+
+    // Parse the name to determine type and validate
+    //TODO: move/rename parsePluginName() to parsePackageName()
+    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 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 {
+    const trimmedName = name.trim()
+
+    // If already scoped, use as-is
+    if (trimmedName.startsWith('@')) {
+      return trimmedName
+    }
+
+    // Otherwise, convert using configured prefix
+    return `${this.getPackagePrefix()}${trimmedName}`
+  }
+
+  /**
+   * 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 async readVersion(packagePath: string): Promise<string> {
+    const packageJsonPath = path.join(packagePath, 'package.json')
+    try {
+      const packageJson = await fs.readJson(packageJsonPath)
+      if (!packageJson.version) {
+        throw new Error(`Invalid package structure: package.json at ${packagePath} is missing required version field. ` + `All Launch77 packages must include a valid package.json with a version field.`)
+      }
+      return packageJson.version
+    } catch (error) {
+      // Re-throw our own error messages
+      if (error instanceof Error && error.message.includes('Invalid package structure')) {
+        throw error
+      }
+      // File not found or invalid JSON
+      throw new Error(`Invalid package structure: package.json not found or invalid at ${packagePath}. ` + `All Launch77 packages must include a valid package.json with a version field.`)
+    }
+  }
+
+  /**
+   * 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' }
+   */
+  async resolveLocation(name: string, workspaceRoot: string): Promise<PackageResolution> {
+    const trimmedName = name.trim()
+    const parsed = parsePluginName(trimmedName)
+
+    // If scoped, always use npm (local packages are never scoped)
+    if (parsed.type === 'scoped') {
+      return {
+        source: 'npm',
+        resolvedName: trimmedName,
+        npmPackage: trimmedName,
+      }
+    }
+
+    // Check local workspace directory
+    const localPath = path.join(workspaceRoot, this.getFolderName(), trimmedName)
+    const localExists = await fs.pathExists(localPath)
+
+    if (localExists) {
+      // Verify it's a valid package
+      const isValid = await this.verify(localPath)
+
+      if (isValid) {
+        const version = await this.readVersion(localPath)
+        return {
+          source: 'local',
+          resolvedName: trimmedName,
+          localPath,
+          version,
+        }
+      }
+    }
+
+    // Not found locally or invalid, resolve to npm package
+    const npmPackage = this.toNpmPackageName(trimmedName)
+
+    return {
+      source: 'npm',
+      resolvedName: trimmedName,
+      npmPackage,
+    }
+  }
+}

package/src/infrastructure/template.ts

@@ -6,7 +6,6 @@ import Handlebars from 'handlebars'
 
 export interface TemplateContext {
   appName: string
-  startupName?: string
   port?: string
   [key: string]: string | number | boolean | undefined
 }

package/src/modules/app/commands/create-app.ts

@@ -7,27 +7,19 @@ import ora from 'ora'
 
 import { detectLaunch77Context } from '@launch77/plugin-runtime'
 import { AppService } from '../services/app-svc.js'
-import { APP_TYPES, APP_TYPES_LIST } from '../types/app-types.js'
-
-import type { AppType } from '../types/app-types.js'
 
 export function createAppCommand(): Command {
   const command = new Command('app:create')
-    .argument('<type>', 'App type (api, webapp, marketing-site)')
+    .argument('<template>', 'App template name (e.g., webapp, api, marketing-site)')
     .argument('<app-name>', 'Name of the application')
-    .description('Create a new application')
-    .option('-p, --port <port>', 'Default port for the app')
-    .action(async (type: string, appName: string, options) => {
+    .description('Create a new application from a template')
+    .option('-p, --port <port>', 'Default port for the app (default: 3000)')
+    .action(async (template: string, appName: string, options) => {
       try {
-        // Validate app type
-        if (!APP_TYPES.includes(type as AppType)) {
-          throw new Error(`Invalid app type: ${type}\n\nSupported types: ${APP_TYPES_LIST}`)
-        }
-
-        console.log(chalk.blue(`\n🚀 Creating ${type} app: ${appName}\n`))
+        console.log(chalk.blue(`\n🚀 Creating app: ${appName} from template: ${template}\n`))
 
-        // Set default port based on app type
-        const port = options.port || (type === 'marketing-site' || type === 'webapp' ? '3000' : '4000')
+        // Set default port
+        const port = options.port || '3000'
 
         // Detect context
         const context = await detectLaunch77Context(process.cwd())
@@ -39,7 +31,7 @@ export function createAppCommand(): Command {
         const templateSpinner = ora('Generating app structure...').start()
         let result
         try {
-          result = await appService.createApp({ type: type as AppType, appName, port }, context)
+          result = await appService.createApp({ type: template, appName, port }, context)
           templateSpinner.succeed('App structure generated')
         } catch (error) {
           templateSpinner.fail('Failed to generate app structure')
@@ -47,8 +39,12 @@ export function createAppCommand(): Command {
         }
 
         // Success message
-        console.log(chalk.green(`\n✅ App created successfully at ${path.relative(process.cwd(), result.appPath)}`))
-        console.log(chalk.gray(`\nRun 'npm run dev' from workspace root to start the server at http://localhost:${port}\n`))
+        const relativeAppPath = path.relative(process.cwd(), result.appPath)
+        console.log(chalk.green(`\n✅ App created successfully at ${relativeAppPath}`))
+        console.log(chalk.gray(`\nNext steps:`))
+        console.log(chalk.gray(`  cd ${relativeAppPath}`))
+        console.log(chalk.gray(`  npm run dev`))
+        console.log(chalk.gray(`\nServer will start at http://localhost:${port}\n`))
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
         console.error(chalk.red('Error:'), message)

package/src/modules/app/commands/delete-app.ts

@@ -12,7 +12,7 @@ import { AppService } from '../services/app-svc.js'
 export function deleteAppCommand(): Command {
   const command = new Command('app:delete')
     .argument('<app-name>', 'Name of the app to delete')
-    .description('Delete an app from the startup (requires confirmation)')
+    .description('Delete an app from the workspace (requires confirmation)')
     .action(async (appName: string) => {
       try {
         console.log(chalk.yellow(`\n⚠️  WARNING: You are about to delete the app '${appName}'\n`))

package/src/modules/app/commands/validate-manifest.ts

@@ -25,7 +25,6 @@ export function validateManifestCommand(): Command {
         console.log()
         console.log(chalk.cyan('Manifest details:'))
         console.log(chalk.gray('  Schema version:'), manifest.schemaVersion)
-        console.log(chalk.gray('  App type:'), manifest.type)
         console.log(chalk.gray('  Package:'), manifest.package)
 
         if ('name' in manifest && manifest.name) {

package/src/modules/app/index.ts

@@ -3,7 +3,7 @@ export { AppService } from './services/app-svc.js'
 export { ManifestService } from './services/manifest-svc.js'
 
 // Types
-export type { CreateAppRequest, CreateAppResult, DeleteAppRequest, DeleteAppResult, AppType } from './types/app-types.js'
+export type { CreateAppRequest, CreateAppResult, DeleteAppRequest, DeleteAppResult } from './types/app-types.js'
 export type { AppManifest, DeploymentConfig } from './lib/manifest-schema.js'
 
 // Errors
@@ -12,5 +12,4 @@ export { AppAlreadyExistsError, AppNotFoundError, InvalidAppNameError, TemplateN
 // Commands
 export { createAppCommand } from './commands/create-app.js'
 export { deleteAppCommand } from './commands/delete-app.js'
-export { generateManifestCommand } from './commands/generate-manifest.js'
 export { validateManifestCommand } from './commands/validate-manifest.js'