prjct-cli 0.11.4 → 0.12.0

package/core/infrastructure/migrator/index.ts

@@ -0,0 +1,288 @@
+/**
+ * Migrator
+ * Handles migrations between prjct versions and structures.
+ *
+ * @module infrastructure/migrator
+ * @version 0.3.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../path-manager'
+import configManager from '../config-manager'
+import authorDetector from '../author-detector'
+
+import type {
+  Author,
+  MigrationResult,
+  MigrationOptions,
+  MigrationSummary,
+  MigrateAllOptions,
+  ProjectInfo,
+  LayerCounts
+} from './types'
+
+import { needsMigration, migrateConfigTo030 } from './version-migration'
+import { migrateFiles } from './file-operations'
+import { validateMigration, cleanupLegacyDirectories, checkStatus } from './validation'
+import { findAllProjects } from './project-scanner'
+import { generateReport, generateMigrationSummary } from './reports'
+
+/**
+ * Handles version migrations and project structure updates.
+ * Supports legacy -> global storage migration and config version upgrades.
+ */
+class Migrator {
+  // Re-export helper methods
+  needsMigration = needsMigration
+  migrateConfigTo030 = migrateConfigTo030
+  validateMigration = validateMigration
+  cleanupLegacyDirectories = cleanupLegacyDirectories
+  checkStatus = checkStatus
+  findAllProjects = findAllProjects
+  generateReport = generateReport
+  generateMigrationSummary = generateMigrationSummary
+
+  /**
+   * Perform the complete migration process
+   */
+  async migrate(projectPath: string, options: MigrationOptions = {}): Promise<MigrationResult> {
+    const result: MigrationResult = {
+      success: false,
+      projectId: null,
+      filesCopied: 0,
+      layerCounts: {
+        core: 0,
+        progress: 0,
+        planning: 0,
+        analysis: 0,
+        memory: 0,
+        other: 0,
+      },
+      config: null,
+      author: null,
+      issues: [],
+      dryRun: options.dryRun || false,
+    }
+
+    try {
+      const config = await configManager.readConfig(projectPath)
+      if (config && config.version && config.version.startsWith('0.2.')) {
+        const versionMigration = await migrateConfigTo030(projectPath)
+        result.success = versionMigration.success
+        result.projectId = config.projectId
+        result.filesCopied = 0
+        result.issues = versionMigration.success ? [] : [versionMigration.message]
+        return result
+      }
+
+      const needsStructuralMigration = await configManager.needsMigration(projectPath)
+      if (!needsStructuralMigration) {
+        result.success = false
+        result.issues.push('No migration needed - either no legacy structure or already migrated')
+        return result
+      }
+
+      const detectedAuthor = await authorDetector.detect()
+      result.author = {
+        name: detectedAuthor.name,
+        email: detectedAuthor.email,
+        github: detectedAuthor.github
+      }
+
+      const projectId = pathManager.generateProjectId(projectPath)
+      result.projectId = projectId
+
+      if (options.dryRun) {
+        result.success = true
+        result.issues.push('DRY RUN - No changes were made')
+        return result
+      }
+
+      await pathManager.ensureProjectStructure(projectId)
+
+      // Convert null to undefined for createConfig
+      const authorForConfig = {
+        name: result.author.name || undefined,
+        email: result.author.email || undefined,
+        github: result.author.github || undefined
+      }
+      result.config = await configManager.createConfig(projectPath, authorForConfig)
+
+      const legacyPath = pathManager.getLegacyPrjctPath(projectPath)
+      const globalPath = pathManager.getGlobalProjectPath(projectId)
+
+      const migrationStats = await migrateFiles(legacyPath, globalPath)
+      result.filesCopied = migrationStats.fileCount
+      result.layerCounts = migrationStats.layerCounts
+
+      const validation = await validateMigration(projectId)
+      result.issues = validation.issues
+
+      if (!validation.valid) {
+        result.success = false
+        return result
+      }
+
+      if (options.removeLegacy) {
+        await fs.rm(legacyPath, { recursive: true, force: true })
+        result.legacyRemoved = true
+      } else if (options.cleanupLegacy) {
+        await cleanupLegacyDirectories(projectPath)
+        result.legacyCleaned = true
+      }
+
+      result.success = true
+      return result
+    } catch (error) {
+      result.success = false
+      result.issues.push(`Migration error: ${(error as Error).message}`)
+      return result
+    }
+  }
+
+  /**
+   * Migrate all projects with legacy .prjct directories
+   */
+  async migrateAll(options: MigrateAllOptions = {}): Promise<MigrationSummary> {
+    const {
+      deepScan = false,
+      removeLegacy = false,
+      cleanupLegacy = false,
+      dryRun = false,
+      interactive = false,
+      onProgress = null,
+    } = options
+
+    const summary: MigrationSummary = {
+      success: false,
+      totalFound: 0,
+      alreadyMigrated: 0,
+      successfullyMigrated: 0,
+      failed: 0,
+      skipped: 0,
+      projects: [],
+      errors: [],
+      dryRun,
+    }
+
+    try {
+      if (onProgress) onProgress({ phase: 'scanning', message: 'Searching for projects...' })
+      const projectPaths = await findAllProjects({ deepScan })
+      summary.totalFound = projectPaths.length
+
+      if (projectPaths.length === 0) {
+        summary.success = true
+        return summary
+      }
+
+      for (let i = 0; i < projectPaths.length; i++) {
+        const projectPath = projectPaths[i]
+        const projectName = path.basename(projectPath)
+
+        if (onProgress) {
+          onProgress({
+            phase: 'checking',
+            message: `Checking ${projectName} (${i + 1}/${projectPaths.length})`,
+            current: i + 1,
+            total: projectPaths.length,
+          })
+        }
+
+        try {
+          const status = await checkStatus(projectPath)
+
+          const projectInfo: ProjectInfo = {
+            path: projectPath,
+            name: projectName,
+            status: status.status,
+          }
+
+          if (status.status === 'migrated' || status.status === 'new') {
+            projectInfo.result = 'skipped'
+            projectInfo.reason =
+              status.status === 'migrated' ? 'Already migrated' : 'Not initialized'
+            summary.alreadyMigrated++
+          } else if (status.needsMigration) {
+            if (interactive && onProgress) {
+              const shouldMigrate = await onProgress({
+                phase: 'confirm',
+                message: `Migrate ${projectName}?`,
+                projectPath,
+              })
+              if (!shouldMigrate) {
+                projectInfo.result = 'skipped'
+                projectInfo.reason = 'User skipped'
+                summary.skipped++
+                summary.projects.push(projectInfo)
+                continue
+              }
+            }
+
+            if (onProgress) {
+              onProgress({
+                phase: 'migrating',
+                message: `Migrating ${projectName}...`,
+                current: i + 1,
+                total: projectPaths.length,
+              })
+            }
+
+            const migrationResult = await this.migrate(projectPath, {
+              removeLegacy,
+              cleanupLegacy,
+              dryRun,
+            })
+
+            projectInfo.projectId = migrationResult.projectId || undefined
+            projectInfo.filesCopied = migrationResult.filesCopied
+            projectInfo.layerCounts = migrationResult.layerCounts
+
+            if (migrationResult.success) {
+              projectInfo.result = 'success'
+              summary.successfullyMigrated++
+            } else {
+              projectInfo.result = 'failed'
+              projectInfo.errors = migrationResult.issues
+              summary.failed++
+              summary.errors.push({
+                project: projectName,
+                path: projectPath,
+                issues: migrationResult.issues,
+              })
+            }
+          }
+
+          summary.projects.push(projectInfo)
+        } catch (error) {
+          summary.failed++
+          summary.errors.push({
+            project: projectName,
+            path: projectPath,
+            issues: [(error as Error).message],
+          })
+          summary.projects.push({
+            path: projectPath,
+            name: projectName,
+            result: 'failed',
+            errors: [(error as Error).message],
+          })
+        }
+      }
+
+      summary.success = summary.failed === 0
+      return summary
+    } catch (error) {
+      summary.success = false
+      summary.errors.push({
+        project: 'global',
+        issues: [(error as Error).message],
+      })
+      return summary
+    }
+  }
+}
+
+const migrator = new Migrator()
+export default migrator
+export * from './types'

package/core/infrastructure/migrator/project-scanner.ts

@@ -0,0 +1,89 @@
+/**
+ * Project Scanner
+ * Finds projects with .prjct directories for migration.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import type { FindProjectsOptions } from './types'
+
+/**
+ * Find all projects with .prjct directories on the user's machine
+ */
+export async function findAllProjects(options: FindProjectsOptions = {}): Promise<string[]> {
+  const { deepScan = true } = options
+  const projectDirs: string[] = []
+
+  let searchPaths: string[] = []
+  if (deepScan) {
+    searchPaths = [os.homedir()]
+  } else {
+    const commonDirs = [
+      'Projects',
+      'Documents',
+      'Developer',
+      'Code',
+      'dev',
+      'workspace',
+      'repos',
+      'src',
+      'Apps',
+    ]
+    searchPaths = commonDirs
+      .map((dir) => path.join(os.homedir(), dir))
+      .filter((dirPath) => {
+        try {
+          require('fs').accessSync(dirPath)
+          return true
+        } catch {
+          return false
+        }
+      })
+  }
+
+  const shouldSkip = (dirName: string): boolean => {
+    const skipDirs = [
+      'node_modules',
+      '.git',
+      '.next',
+      'dist',
+      'build',
+      '.cache',
+      'coverage',
+      '.vscode',
+      '.idea',
+      'vendor',
+      '__pycache__',
+    ]
+    return skipDirs.includes(dirName) || (dirName.startsWith('.') && dirName !== '.prjct')
+  }
+
+  const searchDirectory = async (dirPath: string, depth: number = 0): Promise<void> => {
+    if (depth > 10) return
+
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true })
+
+      if (entries.some((entry) => entry.name === '.prjct' && entry.isDirectory())) {
+        projectDirs.push(dirPath)
+        return // Don't search subdirectories if we found a project
+      }
+
+      for (const entry of entries) {
+        if (entry.isDirectory() && !shouldSkip(entry.name)) {
+          const subPath = path.join(dirPath, entry.name)
+          await searchDirectory(subPath, depth + 1)
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  for (const searchPath of searchPaths) {
+    await searchDirectory(searchPath)
+  }
+
+  return projectDirs
+}

package/core/infrastructure/migrator/reports.ts

@@ -0,0 +1,117 @@
+/**
+ * Reports
+ * Generates migration reports.
+ */
+
+import pathManager from '../path-manager'
+import authorDetector from '../author-detector'
+import type { MigrationResult, MigrationSummary } from './types'
+
+/**
+ * Generate a migration report
+ */
+export function generateReport(result: MigrationResult): string {
+  const lines: string[] = []
+
+  lines.push('Migration Report')
+  lines.push('---')
+
+  if (result.dryRun) {
+    lines.push('DRY RUN MODE - No changes were made')
+    lines.push('')
+  }
+
+  if (result.success) {
+    lines.push('Migration successful!')
+    lines.push('')
+    lines.push(`Project ID: ${result.projectId}`)
+    lines.push(`Author: ${authorDetector.formatAuthor(result.author!)}`)
+    lines.push(`Files migrated: ${result.filesCopied}`)
+    lines.push('')
+    lines.push('Files by layer:')
+    for (const [layer, count] of Object.entries(result.layerCounts)) {
+      if (count > 0) {
+        lines.push(`   - ${layer}: ${count} files`)
+      }
+    }
+    lines.push('')
+    lines.push(`Data location: ${result.config?.dataPath}`)
+
+    if (result.legacyRemoved) {
+      lines.push('')
+      lines.push('Legacy .prjct directory removed')
+    }
+  } else {
+    lines.push('Migration failed!')
+    lines.push('')
+    if (result.issues.length > 0) {
+      lines.push('Issues:')
+      for (const issue of result.issues) {
+        lines.push(`   - ${issue}`)
+      }
+    }
+  }
+
+  lines.push('---')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate a summary report for migrateAll results
+ */
+export function generateMigrationSummary(summary: MigrationSummary): string {
+  const lines: string[] = []
+
+  lines.push('Global Migration Report')
+  lines.push('---')
+
+  if (summary.dryRun) {
+    lines.push('DRY RUN MODE - No changes were made')
+    lines.push('')
+  }
+
+  lines.push(`Found: ${summary.totalFound} projects`)
+  lines.push(`Successfully migrated: ${summary.successfullyMigrated}`)
+  lines.push(`Already migrated: ${summary.alreadyMigrated}`)
+  if (summary.skipped > 0) {
+    lines.push(`Skipped: ${summary.skipped}`)
+  }
+  if (summary.failed > 0) {
+    lines.push(`Failed: ${summary.failed}`)
+  }
+  lines.push('')
+
+  if (summary.successfullyMigrated > 0) {
+    lines.push('Successfully Migrated:')
+    summary.projects
+      .filter((p) => p.result === 'success')
+      .forEach((project) => {
+        lines.push(`   - ${project.name}`)
+        lines.push(`     Files: ${project.filesCopied} | ID: ${project.projectId}`)
+      })
+    lines.push('')
+  }
+
+  if (summary.errors.length > 0) {
+    lines.push('Errors:')
+    summary.errors.forEach((error) => {
+      lines.push(`   - ${error.project}`)
+      error.issues.forEach((issue) => lines.push(`     - ${issue}`))
+    })
+    lines.push('')
+  }
+
+  if (summary.success && summary.successfullyMigrated > 0) {
+    lines.push('All projects migrated successfully!')
+    lines.push(`Global data location: ${pathManager.getGlobalBasePath()}`)
+  } else if (summary.totalFound === 0) {
+    lines.push('No legacy projects found')
+  } else if (summary.alreadyMigrated === summary.totalFound) {
+    lines.push('All projects already migrated')
+  }
+
+  lines.push('---')
+
+  return lines.join('\n')
+}

package/core/infrastructure/migrator/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Migrator Types
+ * Type definitions for migration operations.
+ */
+
+export interface Author {
+  name: string | null
+  email: string | null
+  github?: string | null
+  firstContribution?: string
+  lastActivity?: string
+}
+
+export interface LocalConfig {
+  projectId: string
+  dataPath: string
+  authors?: Author[]
+  author?: Author
+  version?: string
+  created?: string
+  lastSync?: string
+}
+
+export interface LayerCounts {
+  core: number
+  progress: number
+  planning: number
+  analysis: number
+  memory: number
+  other: number
+}
+
+export interface MigrationResult {
+  success: boolean
+  projectId: string | null
+  filesCopied?: number
+  filescopied?: number
+  layerCounts: LayerCounts
+  config: LocalConfig | null
+  author: Author | null
+  issues: string[]
+  dryRun: boolean
+  legacyRemoved?: boolean
+  legacyCleaned?: boolean
+}
+
+export interface VersionMigrationResult {
+  success: boolean
+  message: string
+  oldVersion: string | null
+  newVersion: string
+}
+
+export interface ValidationResult {
+  valid: boolean
+  issues: string[]
+}
+
+export interface FileMapping {
+  layer: string
+  filename: string
+}
+
+export interface MigrationStats {
+  fileCount: number
+  layerCounts: LayerCounts
+}
+
+export interface MigrationOptions {
+  removeLegacy?: boolean
+  cleanupLegacy?: boolean
+  dryRun?: boolean
+}
+
+export interface StatusResult {
+  status: string
+  hasLegacy: boolean
+  hasConfig: boolean
+  needsMigration: boolean
+  version: string
+}
+
+export interface ProjectInfo {
+  path: string
+  name: string
+  status?: string
+  result?: string
+  reason?: string
+  projectId?: string
+  filesCopied?: number
+  layerCounts?: LayerCounts
+  errors?: string[]
+}
+
+export interface MigrationSummary {
+  success: boolean
+  totalFound: number
+  alreadyMigrated: number
+  successfullyMigrated: number
+  failed: number
+  skipped: number
+  projects: ProjectInfo[]
+  errors: Array<{ project: string; path?: string; issues: string[] }>
+  dryRun: boolean
+}
+
+export interface MigrateAllOptions {
+  deepScan?: boolean
+  removeLegacy?: boolean
+  cleanupLegacy?: boolean
+  dryRun?: boolean
+  interactive?: boolean
+  onProgress?: (progress: {
+    phase: string
+    message: string
+    current?: number
+    total?: number
+    projectPath?: string
+  }) => boolean | void | Promise<boolean | void>
+}
+
+export interface FindProjectsOptions {
+  deepScan?: boolean
+}

package/core/infrastructure/migrator/validation.ts

@@ -0,0 +1,94 @@
+/**
+ * Validation
+ * Handles migration validation and legacy cleanup.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../path-manager'
+import type { ValidationResult, StatusResult } from './types'
+
+/**
+ * Validate that migration was successful
+ */
+export async function validateMigration(projectId: string): Promise<ValidationResult> {
+  const issues: string[] = []
+
+  const exists = await pathManager.projectExists(projectId)
+  if (!exists) {
+    issues.push('Global project directory not found')
+    return { valid: false, issues }
+  }
+
+  const globalPath = pathManager.getGlobalProjectPath(projectId)
+  const requiredLayers = ['core', 'progress', 'planning', 'analysis', 'memory']
+
+  for (const layer of requiredLayers) {
+    try {
+      await fs.access(path.join(globalPath, layer))
+    } catch {
+      issues.push(`Missing layer directory: ${layer}`)
+    }
+  }
+
+  try {
+    const coreFiles = await fs.readdir(path.join(globalPath, 'core'))
+    if (coreFiles.length === 0) {
+      issues.push('No files found in core directory')
+    }
+  } catch {
+    issues.push('Cannot read core directory')
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  }
+}
+
+/**
+ * Cleanup legacy directories while preserving config
+ * Removes: analysis/, core/, memory/, planning/, progress/, sessions/
+ * Keeps: prjct.config.json
+ */
+export async function cleanupLegacyDirectories(projectPath: string): Promise<void> {
+  const legacyPath = pathManager.getLegacyPrjctPath(projectPath)
+  const layersToRemove = ['analysis', 'core', 'memory', 'planning', 'progress', 'sessions']
+
+  for (const layer of layersToRemove) {
+    const layerPath = path.join(legacyPath, layer)
+    try {
+      await fs.rm(layerPath, { recursive: true, force: true })
+    } catch {
+      // Ignore errors
+    }
+  }
+}
+
+/**
+ * Check migration status for a project
+ */
+export async function checkStatus(projectPath: string): Promise<StatusResult> {
+  const hasLegacy = await pathManager.hasLegacyStructure(projectPath)
+  const hasConfig = await pathManager.hasConfig(projectPath)
+  const needsMigration = hasLegacy && !hasConfig
+
+  let status = 'unknown'
+  if (!hasLegacy && !hasConfig) {
+    status = 'new' // New project, not initialized
+  } else if (!hasLegacy && hasConfig) {
+    status = 'migrated' // Already migrated to v0.2.0
+  } else if (hasLegacy && !hasConfig) {
+    status = 'legacy' // v0.1.0, needs migration
+  } else if (hasLegacy && hasConfig) {
+    status = 'both' // Has both (migration incomplete or manual setup)
+  }
+
+  return {
+    status,
+    hasLegacy,
+    hasConfig,
+    needsMigration,
+    version: hasConfig ? '0.2.0' : hasLegacy ? '0.1.0' : 'none',
+  }
+}