@launch77/cli 1.2.0

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

@@ -0,0 +1,78 @@
+/* eslint-disable no-console */
+import * as path from 'path'
+
+import chalk from 'chalk'
+import { Command } from 'commander'
+
+import { ManifestService } from '../services/manifest-svc.js'
+
+export function validateManifestCommand(): Command {
+  const command = new Command('app:validate-manifest')
+    .description('Validate a Launch77 manifest file')
+    .option('--path <folder>', 'Path to search for manifest (defaults to current directory)')
+    .action(async (options) => {
+      try {
+        const searchPath = options.path ? path.resolve(options.path) : process.cwd()
+
+        console.log(chalk.blue('🔍 Searching for Launch77 manifest (.launch/app.json)...\n'))
+
+        const manifestService = new ManifestService()
+        const { manifest, manifestPath, appRoot } = await manifestService.loadManifest(searchPath)
+
+        console.log(chalk.green('✅ Valid manifest found!\n'))
+        console.log(chalk.gray('Path:'), manifestPath)
+        console.log(chalk.gray('App root:'), appRoot)
+        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) {
+          console.log(chalk.gray('  Name:'), manifest.name)
+        }
+
+        // Check if deployment field exists
+        if (manifest.deployment) {
+          console.log(chalk.gray('  Deployment platform:'), manifest.deployment.platform)
+          if (manifest.deployment.connected) {
+            console.log(chalk.gray('  Connected:'), 'Yes')
+            if (manifest.deployment.projectName) {
+              console.log(chalk.gray('  Project:'), manifest.deployment.projectName)
+            }
+          }
+        }
+
+        console.log()
+        console.log(chalk.green('✨ Manifest validation successful!'))
+
+        // Exit with success code
+        process.exit(0)
+      } catch (error) {
+        console.error(chalk.red('❌ Manifest validation failed:\n'))
+
+        if (error instanceof Error) {
+          // If it's our formatted error with validation issues, print it as-is
+          if (error.message.includes('Manifest validation failed:')) {
+            console.error(error.message)
+          } else {
+            console.error(chalk.red(error.message))
+          }
+        } else {
+          console.error(chalk.red('Unknown error occurred'))
+        }
+
+        console.log()
+        console.log(chalk.gray('To create a new manifest, use:'))
+        console.log(chalk.cyan('  launch77 create-app <type> <name>'))
+        console.log()
+        console.log(chalk.gray('Or create one manually at .launch/app.json following the schema at:'))
+        console.log(chalk.cyan('  launch77/cli/schemas/app.launch77.schema.json'))
+
+        // Exit with error code
+        process.exit(1)
+      }
+    })
+
+  return command
+}

package/src/modules/app/errors/app-errors.ts

@@ -0,0 +1,41 @@
+export class AppAlreadyExistsError extends Error {
+  constructor(appName: string, appPath: string) {
+    super(`App ${appName} already exists at ${appPath}`)
+    this.name = 'AppAlreadyExistsError'
+  }
+}
+
+export class AppNotFoundError extends Error {
+  constructor(appName: string, expectedPath: string) {
+    super(`App '${appName}' does not exist at ${expectedPath}`)
+    this.name = 'AppNotFoundError'
+  }
+}
+
+export class InvalidAppNameError extends Error {
+  constructor(appName: string, reason: string) {
+    super(`Invalid app name '${appName}': ${reason}`)
+    this.name = 'InvalidAppNameError'
+  }
+}
+
+export class TemplateNotFoundError extends Error {
+  constructor(templateType: string) {
+    super(`Template not found for type: ${templateType}`)
+    this.name = 'TemplateNotFoundError'
+  }
+}
+
+export class ManifestNotFoundError extends Error {
+  constructor(searchDir: string) {
+    super(`No Launch77 manifest found in ${searchDir} or any parent directory`)
+    this.name = 'ManifestNotFoundError'
+  }
+}
+
+export class InvalidManifestError extends Error {
+  constructor(message: string) {
+    super(`Invalid manifest: ${message}`)
+    this.name = 'InvalidManifestError'
+  }
+}

package/src/modules/app/index.ts

@@ -0,0 +1,16 @@
+// Services
+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 { AppManifest, DeploymentConfig } from './lib/manifest-schema.js'
+
+// Errors
+export { AppAlreadyExistsError, AppNotFoundError, InvalidAppNameError, TemplateNotFoundError, ManifestNotFoundError, InvalidManifestError } from './errors/app-errors.js'
+
+// 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'

package/src/modules/app/lib/manifest-schema.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+
+import type { AppType } from '../types/app-types.js'
+
+// Deployment configuration
+export type DeploymentConfig = {
+  platform: 'vercel'
+  connected: boolean
+  connectedAt?: string
+  projectName?: string
+}
+
+// App manifest
+export type AppManifest = {
+  schemaVersion: 1
+  name: string
+  type: AppType | 'marketing' // Support both 'marketing' and 'marketing-site'
+  package: string
+  deployment?: DeploymentConfig
+}
+
+// Zod schemas
+const deploymentConfigZ = z.object({
+  platform: z.literal('vercel'),
+  connected: z.boolean(),
+  connectedAt: z.string().optional(),
+  projectName: z.string().optional(),
+})
+
+// Main manifest schema - strict mode to reject extra fields
+// Note: Manifests store 'marketing' but we accept 'marketing-site' in commands
+export const manifestZ = z
+  .object({
+    schemaVersion: z.literal(1),
+    name: z.string().min(1),
+    type: z.enum(['marketing', 'webapp', 'api']),
+    package: z.string().min(1),
+    deployment: deploymentConfigZ.optional(),
+  })
+  .strict()
+
+/**
+ * Parse and validate a manifest from unknown JSON data
+ * @param json - Unknown JSON data to parse
+ * @returns Validated AppManifest
+ * @throws ZodError with aggregated error messages
+ */
+export function parseManifest(json: unknown): AppManifest {
+  try {
+    return manifestZ.parse(json) as AppManifest
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Format error messages nicely
+      const errorMessages = error.issues
+        .map((err: z.ZodIssue) => {
+          const path = err.path.join('.')
+          return `  - ${path ? `${path}: ` : ''}${err.message}`
+        })
+        .join('\n')
+
+      throw new Error(`Manifest validation failed:\n${errorMessages}`)
+    }
+    throw error
+  }
+}

package/src/modules/app/services/app-svc.ts

@@ -0,0 +1,115 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+
+import { ManifestService } from './manifest-svc.js'
+import * as filesystem from '../../../infrastructure/filesystem.js'
+import * as npm from '../../../infrastructure/npm.js'
+import { generateFromTemplate } from '../../../infrastructure/template-generator.js'
+import { templateExists } from '../../../infrastructure/template.js'
+import { validateWorkspaceContext } from '../../../utils/launch77-validation.js'
+import { validateAppName } from '../../../utils/validation.js'
+
+import type { Launch77Context } from '../../../utils/launch77-context.js'
+import type { CreateAppRequest, CreateAppResult, DeleteAppRequest, DeleteAppResult } from '../types/app-types.js'
+
+export class AppService {
+  private manifestService: ManifestService
+
+  constructor() {
+    this.manifestService = new ManifestService()
+  }
+
+  /**
+   * Create a new app from template
+   */
+  async createApp(request: CreateAppRequest, context: Launch77Context): Promise<CreateAppResult> {
+    const { type, appName, port } = request
+
+    // 1. Validate app name
+    const nameValidation = validateAppName(appName)
+    if (!nameValidation.valid) {
+      throw new Error(nameValidation.errorMessage)
+    }
+
+    // 2. Validate workspace context
+    const contextValidation = validateWorkspaceContext(context)
+    if (!contextValidation.valid) {
+      throw new Error(contextValidation.errorMessage)
+    }
+
+    // 3. Determine app path
+    const appPath = path.join(context.appsDir, appName)
+
+    // 4. Check if app already exists
+    if (await fs.pathExists(appPath)) {
+      throw new Error(`App ${appName} already exists at ${appPath}`)
+    }
+
+    // 5. Validate template exists
+    if (!(await templateExists(type))) {
+      throw new Error(`Unknown app type: ${type}. Currently supported: api, webapp, marketing-site`)
+    }
+
+    // 6. Generate from template (context already has packageName computed)
+    await generateFromTemplate(type, appPath, appName, context, { port })
+
+    // 7. Generate and write app manifest
+    const manifest = this.manifestService.generateManifest(type, appName, context, { port })
+    const launchDir = path.join(appPath, '.launch')
+    await filesystem.ensureDir(launchDir)
+    const manifestPath = path.join(launchDir, 'app.json')
+    await filesystem.writeJSON(manifestPath, manifest)
+
+    // 8. Install dependencies
+    await npm.install(context.workspaceRoot)
+
+    return {
+      appPath,
+      appName,
+      type,
+    }
+  }
+
+  /**
+   * Delete an existing app
+   */
+  async deleteApp(request: DeleteAppRequest, context: Launch77Context): Promise<DeleteAppResult> {
+    const { appName } = request
+
+    // 1. Validate app name
+    const nameValidation = validateAppName(appName)
+    if (!nameValidation.valid) {
+      throw new Error(nameValidation.errorMessage)
+    }
+
+    // 2. Validate workspace context
+    const contextValidation = validateWorkspaceContext(context)
+    if (!contextValidation.valid) {
+      throw new Error(contextValidation.errorMessage)
+    }
+
+    // 3. Determine app path
+    const appPath = path.join(context.appsDir, appName)
+
+    // 4. Check if app exists
+    if (!(await fs.pathExists(appPath))) {
+      throw new Error(`App '${appName}' does not exist.\n\n` + `Expected location: ${appPath}\n\n` + `Available apps:\n` + `  cd apps/\n` + `  ls`)
+    }
+
+    // 5. Check for Docker resources
+    const dockerComposePath = path.join(appPath, 'docker-compose.db.yml')
+    const hasDockerResources = await fs.pathExists(dockerComposePath)
+
+    // 6. Delete the app directory
+    await fs.remove(appPath)
+
+    // 7. Update dependencies
+    await npm.install(context.workspaceRoot)
+
+    return {
+      appName,
+      hadDockerResources: hasDockerResources,
+    }
+  }
+}

package/src/modules/app/services/manifest-svc.ts

@@ -0,0 +1,144 @@
+import * as fs from 'fs/promises'
+import * as path from 'path'
+
+import { parseManifest } from '../lib/manifest-schema.js'
+
+import type { Launch77Context } from '../../../utils/launch77-context.js'
+import type { AppManifest } from '../lib/manifest-schema.js'
+
+/**
+ * Convert kebab-case to Title Case
+ * e.g., "my-startup-name" -> "My Startup Name"
+ */
+function toTitleCase(str: string): string {
+  return str
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Generate a manifest for a marketing app
+ */
+function generateMarketingManifest(appName: string, context: Launch77Context): AppManifest {
+  const workspaceName = context.workspaceName
+
+  return {
+    schemaVersion: 1,
+    name: `${toTitleCase(workspaceName)} Marketing`,
+    type: 'marketing',
+    package: `@${workspaceName}/${appName}`,
+  }
+}
+
+/**
+ * Generate a manifest for a webapp
+ */
+function generateWebappManifest(appName: string, context: Launch77Context): AppManifest {
+  const workspaceName = context.workspaceName
+
+  return {
+    schemaVersion: 1,
+    name: `${toTitleCase(workspaceName)} Web`,
+    type: 'webapp',
+    package: `@${workspaceName}/${appName}`,
+  }
+}
+
+/**
+ * Generate a manifest for an API app
+ */
+function generateApiManifest(appName: string, context: Launch77Context): AppManifest {
+  const workspaceName = context.workspaceName
+
+  return {
+    schemaVersion: 1,
+    name: `${toTitleCase(workspaceName)} API`,
+    type: 'api',
+    package: `@${workspaceName}/${appName}`,
+  }
+}
+
+export class ManifestService {
+  /**
+   * Generate an app manifest based on app type
+   */
+  generateManifest(type: string, appName: string, context: Launch77Context, _options: { port?: string }): AppManifest {
+    switch (type) {
+      case 'marketing-site':
+      case 'marketing':
+        return generateMarketingManifest(appName, context)
+
+      case 'webapp':
+        return generateWebappManifest(appName, context)
+
+      case 'api':
+        return generateApiManifest(appName, context)
+
+      default:
+        throw new Error(`Unsupported app type for manifest generation: ${type}. Supported types: api, webapp, marketing-site`)
+    }
+  }
+
+  /**
+   * Load and validate a Launch77 app manifest file
+   * @param startDir - Directory to start searching from (defaults to process.cwd())
+   * @returns Object containing manifest, manifestPath, and appRoot
+   * @throws Error if manifest not found or invalid
+   */
+  async loadManifest(startDir?: string): Promise<{
+    manifest: AppManifest
+    manifestPath: string
+    appRoot: string
+  }> {
+    const searchDir = startDir || process.cwd()
+    let currentDir = path.resolve(searchDir)
+    const root = path.parse(currentDir).root
+
+    // Walk up the directory tree looking for .launch/app.json
+    while (currentDir !== root) {
+      const manifestPath = path.join(currentDir, '.launch', 'app.json')
+
+      try {
+        const fileContent = await fs.readFile(manifestPath, 'utf-8')
+        const jsonData = JSON.parse(fileContent)
+        const manifest = parseManifest(jsonData)
+
+        return {
+          manifest,
+          manifestPath,
+          appRoot: currentDir,
+        }
+      } catch (error) {
+        // If file doesn't exist, continue searching up
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          const parentDir = path.dirname(currentDir)
+          if (parentDir === currentDir) {
+            break // Reached root
+          }
+          currentDir = parentDir
+          continue
+        }
+
+        // If JSON parse error or validation error, throw with helpful message
+        if (error instanceof SyntaxError) {
+          throw new Error(`Invalid JSON in ${manifestPath}: ${error.message}`)
+        }
+
+        // Re-throw validation errors as-is
+        throw error
+      }
+    }
+
+    throw new Error(`No Launch77 manifest found in ${searchDir} or any parent directory.\n` + `Looking for .launch/app.json.\n` + `Create one using 'launch77 create-app' or manually add a .launch/app.json file.`)
+  }
+
+  /**
+   * Save a manifest file
+   * @param manifestPath - Path to save the manifest
+   * @param manifest - Manifest data to save
+   */
+  async saveManifest(manifestPath: string, manifest: AppManifest): Promise<void> {
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8')
+  }
+}

package/src/modules/app/types/app-types.ts

@@ -0,0 +1,27 @@
+// Supported app types
+export const APP_TYPES = ['api', 'webapp', 'marketing-site'] as const
+export type AppType = (typeof APP_TYPES)[number]
+
+// Display list for error messages
+export const APP_TYPES_LIST = APP_TYPES.join(', ')
+
+export interface CreateAppRequest {
+  type: AppType
+  appName: string
+  port: string
+}
+
+export interface CreateAppResult {
+  appPath: string
+  appName: string
+  type: AppType
+}
+
+export interface DeleteAppRequest {
+  appName: string
+}
+
+export interface DeleteAppResult {
+  appName: string
+  hadDockerResources: boolean
+}

package/src/modules/catalog/commands/generate.ts

@@ -0,0 +1,115 @@
+/**
+ * CLI command for generating catalog metadata files
+ */
+
+import path from 'path'
+
+import chalk from 'chalk'
+import { Command } from 'commander'
+import ora from 'ora'
+
+import { readCatalogConfig } from '../config/catalog-config.js'
+import { CatalogGeneratorService } from '../services/catalog-generator-svc.js'
+import { printQualityReport } from '../utils/quality-reporter.js'
+
+interface GenerateOptions {
+  library: string
+  config: string
+  strict?: boolean
+}
+
+/**
+ * Create the catalog:generate command
+ */
+export function createGenerateCommand(): Command {
+  const command = new Command('catalog:generate')
+    .description('Generate catalog metadata for a component library')
+    .option('-l, --library <path>', 'Library directory path', process.cwd())
+    .option('-c, --config <file>', 'Config file name', 'catalog.config.js')
+    .option('--no-strict', 'Allow generation with validation errors (warnings only)')
+    .action(async (options: GenerateOptions) => {
+      try {
+        await generateCatalog(options)
+      } catch (error) {
+        console.error(chalk.red('\\n✗ Catalog generation failed\\n'))
+        if (error instanceof Error) {
+          console.error(chalk.red(error.message))
+        } else {
+          console.error(chalk.red(String(error)))
+        }
+        process.exit(1)
+      }
+    })
+
+  return command
+}
+
+/**
+ * Execute catalog generation
+ */
+async function generateCatalog(options: GenerateOptions): Promise<void> {
+  const libraryPath = path.resolve(options.library)
+
+  console.log(chalk.blue('\\n📚 Generating catalog metadata...\\n'))
+  console.log(chalk.gray('Library: ' + libraryPath))
+  console.log(chalk.gray('Config: ' + options.config + '\\n'))
+
+  // Read and validate configuration
+  const spinner = ora('Reading configuration...').start()
+
+  let config
+  try {
+    config = await readCatalogConfig(libraryPath)
+    spinner.succeed('Configuration loaded')
+  } catch (error) {
+    spinner.fail('Failed to load configuration')
+    throw error
+  }
+
+  // Override strict mode if --no-strict flag provided
+  if (options.strict === false) {
+    config.validation.strict = false
+    console.log(chalk.yellow('⚠ Running in non-strict mode (validation errors will not fail build)\\n'))
+  }
+
+  // Display configuration
+  console.log(chalk.gray('Configuration:'))
+  console.log(chalk.gray('  Package: ' + config.packageName))
+  console.log(chalk.gray('  Catalog version: ' + config.catalogVersion))
+  console.log(chalk.gray('  Output file: ' + config.outputFile))
+  console.log(chalk.gray('  Strict mode: ' + (config.validation.strict ? 'enabled' : 'disabled') + '\\n'))
+
+  // Generate catalog
+  const generationSpinner = ora('Scanning components...').start()
+
+  const service = new CatalogGeneratorService()
+  const result = await service.generateForLibrary(libraryPath, config)
+
+  generationSpinner.stop()
+
+  // Display quality report
+  console.log(chalk.blue('\\n📊 Quality Report\\n'))
+  printQualityReport(result.qualityReport, config.validation.strict)
+
+  // Handle result
+  if (!result.success) {
+    console.log(chalk.red('\\n✗ Catalog generation failed\\n'))
+    console.log(chalk.red('Validation errors must be fixed before building.'))
+    console.log(chalk.gray('\\nTo fix:'))
+    console.log(chalk.gray('  1. Add @launch77-component JSDoc to components listed above'))
+    console.log(chalk.gray('  2. Or add @launch77-ignore to exclude internal/WIP components'))
+    console.log(chalk.gray('  3. Or run with --no-strict to allow warnings\\n'))
+    process.exit(1)
+  }
+
+  // Success!
+  console.log(chalk.green('\\n✓ Generated ' + config.outputFile))
+  console.log(chalk.gray('  Quality score: ' + result.qualityReport.qualityScore + '%'))
+  console.log(chalk.gray('  Total components: ' + result.qualityReport.totalComponents))
+
+  if (result.warnings.length > 0) {
+    console.log(chalk.yellow('  Warnings: ' + result.warnings.length))
+  }
+
+  console.log()
+}

package/src/modules/catalog/commands/scan.ts

@@ -0,0 +1,48 @@
+import chalk from 'chalk'
+import { Command } from 'commander'
+
+import { detectMonorepoContext } from '../../../utils/monorepo.js'
+import { CatalogService } from '../services/catalog-svc.js'
+
+/**
+ * Scan command - Generate catalog.json from Launch77 artifacts
+ *
+ * Scans UI components, libraries, plugins, and utilities from the Launch77 monorepo
+ * and generates a machine-readable catalog for AI discovery.
+ */
+export function scanCommand(): Command {
+  const command = new Command('catalog:scan')
+    .description('Scan Launch77 artifacts and generate catalog.json')
+    .option('--no-strict', 'Skip validation errors and generate catalog anyway')
+    .option('--quiet', 'Suppress quality report output')
+    .action(async (options) => {
+      try {
+        const context = await detectMonorepoContext(process.cwd())
+
+        if (!context.isValid) {
+          console.error(chalk.red('\n✖ Must be run from within a Launch77 monorepo\n'))
+          process.exit(1)
+        }
+
+        const catalogService = new CatalogService()
+
+        await catalogService.scanCatalog(context, {
+          strict: options.strict,
+          quiet: options.quiet,
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+
+        if (message.includes('validation failed')) {
+          console.log(chalk.red('\n❌ Catalog validation failed in strict mode.\n'))
+          console.log(chalk.yellow('Fix validation errors or use --no-strict flag to generate catalog anyway.\n'))
+        } else {
+          console.error(chalk.red(`\n✖ Error: ${message}\n`))
+        }
+
+        process.exit(1)
+      }
+    })
+
+  return command
+}