@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/migration.cjs

@@ -0,0 +1,352 @@
+/**
+ * Migration — v1-to-v2 file structure migration
+ *
+ * Detects v1 DGS installs (single project at .planning/ root) and migrates
+ * them to v2 multi-project structure (.planning/projects/<slug>/) using git mv
+ * for history preservation.
+ *
+ * Entry point: cmdReposInitProduct detects v1 and offers migration.
+ * The workflow handles the user prompt; this module handles the moves.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, isV2Install, generateSlugInternal, output, error } = require('./core.cjs');
+const { writeReposMd } = require('./repos.cjs');
+const { regenerateProjectsMd } = require('./projects.cjs');
+const { writeConfigField } = require('./config.cjs');
+const { getPlanningRoot, PROJECTS_DIR } = require('./paths.cjs');
+
+// ─── v1 Detection ────────────────────────────────────────────────────────────
+
+/**
+ * Detect whether cwd is a v1 DGS install.
+ *
+ * v1 marker: .planning/PROJECT.md exists at root WITHOUT PROJECTS.md or REPOS.md.
+ * If v1 detected, extracts project name from heading and generates slug.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ isV1: boolean, projectName?: string, slug?: string }}
+ */
+function detectV1Install(cwd) {
+  // v1 always uses .planning/ — intentionally hardcoded for v1 source detection
+  const projectMdPath = path.join(cwd, '.planning', 'PROJECT.md');
+  const projectsMdPath = path.join(cwd, '.planning', 'PROJECTS.md');
+  const reposMdPath = path.join(cwd, '.planning', 'REPOS.md');
+
+  // Check if PROJECT.md exists
+  const projectContent = safeReadFile(projectMdPath);
+  if (!projectContent) {
+    return { isV1: false };
+  }
+
+  // Check v2 markers — if either exists, it's already v2 (or partially migrated)
+  const projectsMdContent = safeReadFile(projectsMdPath);
+  if (projectsMdContent && projectsMdContent.startsWith('# Projects')) {
+    return { isV1: false };
+  }
+
+  const reposMdContent = safeReadFile(reposMdPath);
+  if (reposMdContent && reposMdContent.startsWith('# Repos')) {
+    return { isV1: false };
+  }
+
+  // It's v1 — extract project name from heading
+  let projectName = null;
+
+  // Try "# Project: Name" format first
+  const colonMatch = projectContent.match(/^#\s+Project:\s+(.+)$/m);
+  if (colonMatch) {
+    projectName = colonMatch[1].trim();
+  }
+
+  // Try "# Project Name" format (no colon)
+  if (!projectName) {
+    const headingMatch = projectContent.match(/^#\s+(.+)$/m);
+    if (headingMatch) {
+      projectName = headingMatch[1].trim();
+    }
+  }
+
+  // Fall back to directory name
+  if (!projectName) {
+    projectName = path.basename(cwd);
+  }
+
+  const slug = generateSlugInternal(projectName) || path.basename(cwd).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+
+  return { isV1: true, projectName, slug };
+}
+
+// ─── Precondition Validation ─────────────────────────────────────────────────
+
+/**
+ * Validate that migration can proceed.
+ *
+ * Checks:
+ * 1. Not already a v2 install
+ * 2. .planning/PROJECT.md exists (v1 marker)
+ * 3. Git working tree is clean (no uncommitted changes)
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateMigrationPreconditions(cwd) {
+  // Check if already v2
+  if (isV2Install(cwd)) {
+    return { valid: false, reason: 'Already a v2 install. Migration not needed.' };
+  }
+
+  // Check if v1 marker exists — v1 always uses .planning/
+  const projectMdPath = path.join(cwd, '.planning', 'PROJECT.md');
+  if (!safeReadFile(projectMdPath)) {
+    return { valid: false, reason: 'No .planning/PROJECT.md found. Not a v1 install.' };
+  }
+
+  // Check git working tree is clean
+  const gitStatus = execGit(cwd, ['status', '--porcelain']);
+  if (gitStatus.exitCode !== 0) {
+    return { valid: false, reason: 'Not a git repository or git command failed.' };
+  }
+  if (gitStatus.stdout.trim().length > 0) {
+    return { valid: false, reason: 'Working tree has uncommitted changes. Please commit or stash before migration.' };
+  }
+
+  return { valid: true };
+}
+
+// ─── Backup Tag ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a pre-migration backup tag for safe rollback.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ tagged: boolean, reason?: string }}
+ */
+function createBackupTag(cwd) {
+  const result = execGit(cwd, ['tag', 'dgs-pre-v2-migration']);
+  if (result.exitCode !== 0) {
+    // Check if tag already exists or no git
+    if (result.stderr.includes('already exists')) {
+      return { tagged: false, reason: 'Tag dgs-pre-v2-migration already exists.' };
+    }
+    return { tagged: false, reason: result.stderr || 'Failed to create tag.' };
+  }
+  return { tagged: true };
+}
+
+// ─── Migration Planning ─────────────────────────────────────────────────────
+
+// Directories to move (project-level, order: directories first)
+const DIRS_TO_MOVE = ['phases', 'research', 'todos', 'quick', 'debug'];
+
+// Files to move (project-level)
+const FILES_TO_MOVE = ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+
+/**
+ * Collect all migration move operations as a plan (pure computation, no side effects).
+ *
+ * Returns an array of { relSource, relTarget, isDir } for all items that exist
+ * and need moving. Directories are listed before files to maximize git rename detection.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Project slug for subfolder name
+ * @returns {{ moves: Array<{relSource: string, relTarget: string, isDir: boolean}>, targetDir: string }}
+ */
+function collectMigrationMoves(cwd, slug) {
+  // v1 always uses .planning/ — migration source is always the .planning directory
+  const planningDir = path.join(cwd, '.planning');
+  const targetDir = path.join(planningDir, PROJECTS_DIR, slug);
+  const moves = [];
+
+  // Directories first
+  for (const dir of DIRS_TO_MOVE) {
+    const sourcePath = path.join(planningDir, dir);
+    if (fs.existsSync(sourcePath)) {
+      moves.push({
+        relSource: path.join('.planning', dir),
+        relTarget: path.join('.planning', PROJECTS_DIR, slug, dir),
+        isDir: true,
+      });
+    }
+  }
+
+  // Then files
+  for (const file of FILES_TO_MOVE) {
+    const sourcePath = path.join(planningDir, file);
+    if (fs.existsSync(sourcePath)) {
+      moves.push({
+        relSource: path.join('.planning', file),
+        relTarget: path.join('.planning', PROJECTS_DIR, slug, file),
+        isDir: false,
+      });
+    }
+  }
+
+  return { moves, targetDir };
+}
+
+/**
+ * Validate that all planned moves can succeed.
+ *
+ * Checks:
+ * - Each source exists on disk
+ * - Each target does NOT already exist (would cause git mv to fail)
+ *
+ * @param {string} cwd - Working directory
+ * @param {Array<{relSource: string, relTarget: string, isDir: boolean}>} moves - Planned moves
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateMoves(cwd, moves) {
+  const errors = [];
+
+  for (const move of moves) {
+    const absSource = path.join(cwd, move.relSource);
+    if (!fs.existsSync(absSource)) {
+      errors.push('Source does not exist: ' + move.relSource);
+    }
+
+    const absTarget = path.join(cwd, move.relTarget);
+    if (fs.existsSync(absTarget)) {
+      errors.push('Target already exists: ' + move.relTarget);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ─── Core Migration ──────────────────────────────────────────────────────────
+
+/**
+ * Perform the v1-to-v2 migration.
+ *
+ * Uses a dry-run-then-execute pattern:
+ * 1. Collect planned moves (collectMigrationMoves)
+ * 2. Validate all moves can succeed (validateMoves)
+ * 3. Execute moves with rollback on failure
+ * 4. Commit with diff.renameLimit=1000 for large projects
+ * 5. Create v2 marker files in a separate commit
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Project slug for subfolder name
+ * @returns {{ migrated: boolean, slug: string, files_moved: string[], repos_created: boolean, project_created: boolean, error?: string, rollback?: boolean }}
+ */
+function migrateV1ToV2(cwd, slug) {
+  // v1 always uses .planning/ — migration operates on the .planning directory
+  const planningDir = path.join(cwd, '.planning');
+
+  // Step 1: Collect planned moves
+  const { moves, targetDir } = collectMigrationMoves(cwd, slug);
+
+  // Create the target project directory (needed before validation and git mv)
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // Step 2: Validate all moves
+  const validation = validateMoves(cwd, moves);
+  if (!validation.valid) {
+    // Clean up created target directory
+    try { fs.rmdirSync(targetDir); } catch (_e) { /* ignore */ }
+    return {
+      migrated: false,
+      slug,
+      files_moved: [],
+      repos_created: false,
+      project_created: false,
+      error: 'Validation failed: ' + validation.errors.join('; '),
+    };
+  }
+
+  // Step 3: Execute moves with rollback on failure
+  const filesMoved = [];
+
+  try {
+    for (const move of moves) {
+      const result = execGit(cwd, ['mv', move.relSource, move.relTarget]);
+      if (result.exitCode !== 0) {
+        throw new Error('git mv failed for ' + move.relSource + ': ' + result.stderr);
+      }
+      filesMoved.push(move.isDir ? path.basename(move.relSource) + '/' : path.basename(move.relSource));
+    }
+  } catch (err) {
+    // Rollback: restore all files to pre-move state
+    execGit(cwd, ['checkout', 'HEAD', '--', '.']);
+    execGit(cwd, ['clean', '-fd', path.join('.planning', PROJECTS_DIR, slug)]);
+    return {
+      migrated: false,
+      slug,
+      files_moved: [],
+      repos_created: false,
+      project_created: false,
+      error: 'Migration failed: ' + err.message,
+      rollback: true,
+    };
+  }
+
+  // Step 4: Commit the moves (git mv already stages files, no git add -A needed)
+  // Use diff.renameLimit=1000 to handle projects with many files
+  execGit(cwd, ['-c', 'diff.renameLimit=1000', 'commit', '-m', 'chore: migrate to DGS v2 multi-project structure']);
+
+  // Step 5: Post-migration setup — Create REPOS.md
+  const dirName = path.basename(cwd);
+  writeReposMd(cwd, [{ name: dirName, path: '.', url: '', description: '' }]);
+
+  // Post-migration setup: Set current_project in config.json
+  writeConfigField(cwd, 'current_project', slug);
+
+  // Post-migration setup: Create PROJECTS.md from migrated project state
+  regenerateProjectsMd(cwd);
+
+  // Commit post-migration setup (new files need git add -A)
+  execGit(cwd, ['add', '-A']);
+  execGit(cwd, ['commit', '-m', 'chore: create v2 marker files after migration']);
+
+  return {
+    migrated: true,
+    slug,
+    files_moved: filesMoved,
+    repos_created: true,
+    project_created: true,
+  };
+}
+
+// ─── CLI Command ─────────────────────────────────────────────────────────────
+
+/**
+ * CLI entry point for migration.
+ * Called from repos migrate <slug> routing.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Project slug
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdMigrateV1ToV2(cwd, slug, raw) {
+  // Validate preconditions
+  const preconditions = validateMigrationPreconditions(cwd);
+  if (!preconditions.valid) {
+    error(preconditions.reason);
+  }
+
+  // Create backup tag
+  const tag = createBackupTag(cwd);
+
+  // Perform migration
+  const result = migrateV1ToV2(cwd, slug);
+
+  output({
+    ...result,
+    backup_tag: tag.tagged ? 'dgs-pre-v2-migration' : null,
+    backup_tag_note: tag.tagged ? null : tag.reason,
+  }, raw);
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  detectV1Install,
+  validateMigrationPreconditions,
+  createBackupTag,
+  collectMigrationMoves,
+  validateMoves,
+  migrateV1ToV2,
+  cmdMigrateV1ToV2,
+};