@ktpartners/dgs-platform 2.7.5 → 2.9.0

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

@@ -1,352 +1,327 @@
 /**
- * Migration — v1-to-v2 file structure migration
+ * Migration -- .planning/ to root layout migration engine
  *
- * 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.
+ * Provides migrateDotPlanningToRoot() which moves all planning files from
+ * .planning/ to repo root. Handles conflict detection (abort on different
+ * content, resolve identical content), partial migration, .gitignore
+ * rewriting, config.local.json cleanup, dgs.config.json rename, git mv /
+ * fs.rename duality, atomic commit, rollback on failure, and dry-run
+ * data collection.
  */
 
 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');
+const { execGit, safeReadFile, error } = require('./core.cjs');
 
-// ─── v1 Detection ────────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 
 /**
- * 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.
+ * Recursively collects all file paths under `dir`, returning paths
+ * relative to `base`. Skips .git directories.
  *
- * @param {string} cwd - Working directory
- * @returns {{ isV1: boolean, projectName?: string, slug?: string }}
+ * @param {string} dir - Directory to walk
+ * @param {string} base - Base directory for relative path calculation
+ * @returns {string[]} Array of relative file paths
  */
-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();
+function collectFiles(dir, base) {
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === '.git') continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath, base));
+    } else {
+      results.push(path.relative(base, fullPath));
     }
   }
-
-  // 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 };
+  return results;
 }
 
-// ─── 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)
+ * Returns true if `cwd` is inside a git working tree.
  *
  * @param {string} cwd - Working directory
- * @returns {{ valid: boolean, reason?: string }}
+ * @returns {boolean}
  */
-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 };
+function isGitRepo(cwd) {
+  const result = execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+  return result.exitCode === 0;
 }
 
-// ─── Backup Tag ──────────────────────────────────────────────────────────────
-
 /**
- * Create a pre-migration backup tag for safe rollback.
+ * Returns true if the git working tree at `cwd` has no uncommitted changes.
  *
- * @param {string} cwd - Working directory
- * @returns {{ tagged: boolean, reason?: string }}
+ * @param {string} cwd - Working directory (should be repo root)
+ * @returns {boolean}
  */
-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 };
+function isCleanWorkingTree(cwd) {
+  const result = execGit(cwd, ['status', '--porcelain']);
+  return result.stdout === '';
 }
 
-// ─── Migration Planning ─────────────────────────────────────────────────────
-
-// Directories to move (project-level, order: directories first)
-const DIRS_TO_MOVE = ['phases', 'research', 'quick', 'debug'];
-
-// Files to move (project-level)
-const FILES_TO_MOVE = ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+// ─── Main Migration Function ──────────────────────────────────────────────────
 
 /**
- * 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.
+ * Migrates all planning files from .planning/ to repo root.
  *
- * @param {string} cwd - Working directory
- * @param {string} slug - Project slug for subfolder name
- * @returns {{ moves: Array<{relSource: string, relTarget: string, isDir: boolean}>, targetDir: string }}
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @param {Object} [options] - Migration options
+ * @param {boolean} [options.dryRun=false] - If true, return actions without modifying files
+ * @returns {{
+ *   migrated: boolean,
+ *   filesMoved: number,
+ *   identicalResolved: number,
+ *   commitHash: string|null,
+ *   dryRun: boolean,
+ *   actions: Array<{type: string, from: string, to: 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 = [];
+function migrateDotPlanningToRoot(cwd, options) {
+  const opts = options || {};
+  const dryRun = opts.dryRun || false;
+
+  // 1. Resolve paths
+  const inGit = isGitRepo(cwd || process.cwd());
+  let root;
+  if (inGit) {
+    root = execGit(cwd || process.cwd(), ['rev-parse', '--show-toplevel']).stdout;
+  } else {
+    root = path.resolve(cwd || process.cwd());
+  }
 
-  // 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,
-      });
-    }
+  const dotPlanning = path.join(root, '.planning');
+
+  // 2. Idempotency check (MIG-07)
+  if (!fs.existsSync(dotPlanning) || !fs.statSync(dotPlanning).isDirectory()) {
+    return {
+      migrated: false,
+      filesMoved: 0,
+      identicalResolved: 0,
+      commitHash: null,
+      dryRun: dryRun,
+      actions: [],
+    };
   }
 
-  // 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,
-      });
-    }
+  // 3. Clean working tree check (git only)
+  if (inGit && !isCleanWorkingTree(root)) {
+    error('Migration requires a clean working tree. Commit or stash your changes first, then re-run.');
   }
 
-  return { moves, targetDir };
-}
+  // 4. Collect files in .planning/
+  const planningFiles = collectFiles(dotPlanning, dotPlanning);
 
-/**
- * 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 = [];
+  // 5. Pre-flight conflict scan (MIG-02, MIG-03, MIG-04)
+  const moves = [];
+  const identical = [];
+  const conflicts = [];
 
-  for (const move of moves) {
-    const absSource = path.join(cwd, move.relSource);
-    if (!fs.existsSync(absSource)) {
-      errors.push('Source does not exist: ' + move.relSource);
-    }
+  for (const relPath of planningFiles) {
+    const srcPath = path.join(dotPlanning, relPath);
 
-    const absTarget = path.join(cwd, move.relTarget);
-    if (fs.existsSync(absTarget)) {
-      errors.push('Target already exists: ' + move.relTarget);
+    // 6. Handle dgs.config.json rename (MIG-10)
+    let destRelPath = relPath;
+    if (relPath === 'dgs.config.json') {
+      destRelPath = 'config.json';
     }
-  }
 
-  return { valid: errors.length === 0, errors };
-}
+    const destPath = path.join(root, destRelPath);
 
-// ─── Core Migration ──────────────────────────────────────────────────────────
+    if (fs.existsSync(destPath)) {
+      const srcContent = fs.readFileSync(srcPath, 'utf-8');
+      const destContent = fs.readFileSync(destPath, 'utf-8');
+      if (srcContent === destContent) {
+        identical.push({ relPath, destRelPath, srcPath, destPath });
+      } else {
+        conflicts.push({ relPath, destRelPath, srcPath, destPath });
+      }
+    } else {
+      moves.push({ relPath, destRelPath, srcPath, destPath });
+    }
+  }
 
-/**
- * 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');
+  // Also check if dgs.config.json exists at root (not in .planning) and needs rename
+  const rootDgsConfig = path.join(root, 'dgs.config.json');
+  const rootConfig = path.join(root, 'config.json');
+  if (fs.existsSync(rootDgsConfig) && !fs.existsSync(rootConfig)) {
+    // Only if not already handled via .planning/dgs.config.json
+    const alreadyHandled = moves.some(m => m.relPath === 'dgs.config.json') ||
+                           identical.some(m => m.relPath === 'dgs.config.json') ||
+                           conflicts.some(m => m.relPath === 'dgs.config.json');
+    if (!alreadyHandled) {
+      moves.push({
+        relPath: 'dgs.config.json',
+        destRelPath: 'config.json',
+        srcPath: rootDgsConfig,
+        destPath: rootConfig,
+        isRootRename: true,
+      });
+    }
+  }
 
-  // Step 1: Collect planned moves
-  const { moves, targetDir } = collectMigrationMoves(cwd, slug);
+  // 7. Abort on conflicts (MIG-02)
+  if (conflicts.length > 0) {
+    const fileList = conflicts.map(c => '  - ' + c.relPath + ' (.planning/' + c.relPath + ' vs ./' + c.destRelPath + ')').join('\n');
+    error(
+      'Migration aborted: ' + conflicts.length + ' file(s) have different content in .planning/ and root.\n' +
+      'Resolve these conflicts manually, then re-run:\n' +
+      fileList
+    );
+  }
 
-  // Create the target project directory (needed before validation and git mv)
-  fs.mkdirSync(targetDir, { recursive: true });
+  // 8. Build actions array
+  const actions = [];
+  for (const m of moves) {
+    actions.push({ type: 'move', from: m.isRootRename ? 'dgs.config.json' : '.planning/' + m.relPath, to: m.destRelPath });
+  }
+  for (const i of identical) {
+    actions.push({ type: 'identical', from: '.planning/' + i.relPath, to: i.destRelPath });
+  }
 
-  // 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 */ }
+  // 9. Dry-run exit (OPT-02)
+  if (dryRun) {
     return {
       migrated: false,
-      slug,
-      files_moved: [],
-      repos_created: false,
-      project_created: false,
-      error: 'Validation failed: ' + validation.errors.join('; '),
+      filesMoved: moves.length,
+      identicalResolved: identical.length,
+      commitHash: null,
+      dryRun: true,
+      actions,
     };
   }
 
-  // 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);
+  // 10. Execute file moves
+  for (const m of moves) {
+    if (m.isRootRename) {
+      // Root-level dgs.config.json -> config.json rename
+      if (inGit) {
+        execGit(root, ['mv', 'dgs.config.json', 'config.json']);
+      } else {
+        fs.renameSync(m.srcPath, m.destPath);
+      }
+    } else {
+      // .planning/ file -> root
+      fs.mkdirSync(path.dirname(m.destPath), { recursive: true });
+      if (inGit) {
+        execGit(root, ['-c', 'diff.renameLimit=1000', 'mv', '.planning/' + m.relPath, m.destRelPath]);
+      } else {
+        fs.renameSync(m.srcPath, m.destPath);
       }
-      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']);
+  // 11. Resolve identical conflicts (MIG-03)
+  for (const i of identical) {
+    if (inGit) {
+      execGit(root, ['rm', '-f', '.planning/' + i.relPath]);
+    } else {
+      fs.unlinkSync(i.srcPath);
+    }
+  }
 
-  // Step 5: Post-migration setup — Create REPOS.md
-  const dirName = path.basename(cwd);
-  writeReposMd(cwd, [{ name: dirName, path: '.', url: '', description: '' }]);
+  // 12. Rewrite .gitignore (MIG-05)
+  const gitignorePath = path.join(root, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    const rewritten = content
+      .split('\n')
+      .map(line => {
+        // Handle negation patterns: !.planning/X -> !X
+        if (line.startsWith('!.planning/')) {
+          return '!' + line.slice('!.planning/'.length);
+        }
+        // Handle normal patterns: .planning/X -> X
+        if (line.startsWith('.planning/')) {
+          return line.slice('.planning/'.length);
+        }
+        return line;
+      })
+      .join('\n');
+    fs.writeFileSync(gitignorePath, rewritten);
+  }
 
-  // Post-migration setup: Set current_project in config.json
-  writeConfigField(cwd, 'current_project', slug);
+  // 13. Clean config.local.json (MIG-06)
+  const configLocalPath = path.join(root, 'config.local.json');
+  if (fs.existsSync(configLocalPath)) {
+    try {
+      const configContent = fs.readFileSync(configLocalPath, 'utf-8');
+      const configObj = JSON.parse(configContent);
+      if ('planningRoot' in configObj) {
+        delete configObj.planningRoot;
+        fs.writeFileSync(configLocalPath, JSON.stringify(configObj, null, 2) + '\n');
+      }
+    } catch {
+      // If config.local.json is not valid JSON, skip cleanup
+    }
+  }
 
-  // Post-migration setup: Create PROJECTS.md from migrated project state
-  regenerateProjectsMd(cwd);
+  // 14. Remove empty .planning/ directory
+  if (fs.existsSync(dotPlanning)) {
+    fs.rmSync(dotPlanning, { recursive: true, force: true });
+  }
 
-  // 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']);
+  // 15. Git commit (MIG-11)
+  let commitHash = null;
+  if (inGit) {
+    execGit(root, ['add', '-A']);
+    const commitResult = execGit(root, ['commit', '-m', 'chore: migrate .planning/ to root layout']);
+    if (commitResult.exitCode !== 0) {
+      // Rollback (OPT-03): restore from git on commit failure
+      execGit(root, ['checkout', 'HEAD', '--', '.']);
+      error('Migration commit failed. Original .planning/ layout restored. Error: ' + commitResult.stderr);
+    }
+    const hashResult = execGit(root, ['rev-parse', '--short', 'HEAD']);
+    commitHash = hashResult.stdout;
+  }
 
+  // 16. Return result
   return {
     migrated: true,
-    slug,
-    files_moved: filesMoved,
-    repos_created: true,
-    project_created: true,
+    filesMoved: moves.length,
+    identicalResolved: identical.length,
+    commitHash: inGit ? commitHash : null,
+    dryRun: false,
+    actions,
   };
 }
 
-// ─── CLI Command ─────────────────────────────────────────────────────────────
+// ─── V1 Rejection ────────────────────────────────────────────────────────────
 
 /**
- * CLI entry point for migration.
- * Called from repos migrate <slug> routing.
+ * Reject V1 single-repo layout installations.
+ * Detects .planning/PROJECT.md without PROJECTS.md or REPOS.md markers.
+ * Writes a persistent V1_UNSUPPORTED.md guidance file and exits with code 1.
  *
- * @param {string} cwd - Working directory
- * @param {string} slug - Project slug
- * @param {boolean} raw - Raw output mode
+ * Called from dgs-tools.cjs router -- single call site at CLI entry.
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
  */
-function cmdMigrateV1ToV2(cwd, slug, raw) {
-  // Validate preconditions
-  const preconditions = validateMigrationPreconditions(cwd);
-  if (!preconditions.valid) {
-    error(preconditions.reason);
+function rejectV1Install(cwd) {
+  const resolved = path.resolve(cwd || process.cwd());
+  const dotPlanning = path.join(resolved, '.planning');
+  const v1Marker = path.join(dotPlanning, 'PROJECT.md');
+  if (!fs.existsSync(v1Marker)) return; // No V1 marker, nothing to do
+  const hasProjectsMd = fs.existsSync(path.join(resolved, 'PROJECTS.md')) ||
+                        fs.existsSync(path.join(dotPlanning, 'PROJECTS.md'));
+  const hasReposMd = fs.existsSync(path.join(resolved, 'REPOS.md')) ||
+                     fs.existsSync(path.join(dotPlanning, 'REPOS.md'));
+  if (!hasProjectsMd && !hasReposMd) {
+    const guidancePath = path.join(resolved, 'V1_UNSUPPORTED.md');
+    const guidanceContent = [
+      '# V1 Install Detected', '',
+      'This repository has a DGS V1 (single-repo) layout which is no longer supported.', '',
+      'DGS now requires the V2 multi-project layout. To continue using DGS,',
+      'install an older version that supports V1, or set up a fresh V2 install',
+      'with `/dgs:init-product`.', '',
+      'See the DGS changelog for migration details.', '',
+    ].join('\n');
+    try { fs.writeFileSync(guidancePath, guidanceContent); } catch { /* best effort */ }
+    process.stderr.write('Error: V1 single-repo layout is no longer supported. Install an older DGS version or run /dgs:init-product for a fresh V2 setup. See V1_UNSUPPORTED.md for details.\n');
+    process.exit(1);
   }
-
-  // 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,
-};
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = { migrateDotPlanningToRoot, rejectV1Install };