pi-var 1.0.1

package/extensions/pi-var/src/variation/create.ts

@@ -0,0 +1,127 @@
+/**
+ * Variation creation orchestration
+ */
+
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import type { Variation, VariationType, CreateVariationOptions } from '../types/index';
+import { detectCoWSupport } from '../cow/index';
+import { hasGitRepo } from './merge/strategy';
+import { createCoWVariation } from './create-cow';
+import { createWorktreeVariation } from './create-worktree';
+import { createCopyVariation } from './create-copy';
+import { ensureGlobalGitignore } from '../gitignore/manager';
+import { getProjectName, getProjectHash, generateVariationId } from './paths';
+import { generateVariationName } from '../utils/names';
+
+/**
+ * Get the base directory for variations
+ */
+function getVariationsBaseDir(sourcePath: string): string {
+  const projectName = getProjectName(sourcePath);
+  const projectHash = getProjectHash(sourcePath);
+  return path.join(sourcePath, '.pi', 'variations', `${projectName}-${projectHash}`);
+}
+
+/**
+ * Create a new variation
+ * Auto-selects type: cow > worktree > copy
+ *
+ * CoW variations in git repos automatically get a branch and initial commit
+ * for proper three-way merge semantics (see create-cow.ts).
+ */
+export async function createVariation(
+  sourcePath: string,
+  options: CreateVariationOptions = {}
+): Promise<Variation> {
+  const name = options.name || generateVariationName();
+  const id = generateVariationId();
+  const baseDir = getVariationsBaseDir(sourcePath);
+  const variationPath = path.join(baseDir, name);
+
+  // Ensure base directory exists
+  await fs.mkdir(baseDir, { recursive: true });
+
+  // Check if variation already exists
+  try {
+    await fs.access(variationPath);
+    throw new Error(`Variation "${name}" already exists at ${variationPath}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  let type: VariationType;
+  let branchName: string | undefined;
+  let mergeBaseCommit: string | undefined;
+
+  // Determine variation type
+  if (options.type) {
+    type = options.type;
+  } else {
+    // Auto-select based on CoW detection result (includes EDR awareness)
+    const cowResult = await detectCoWSupport(baseDir);
+    const isGitRepo = await hasGitRepo(sourcePath);
+
+    // Use the recommended type from detection
+    type = cowResult.recommendedType;
+
+    // If worktree is recommended but not a git repo, fall back to copy
+    if (type === 'worktree' && !isGitRepo) {
+      type = 'copy';
+    }
+
+    // Log EDR detection info if relevant (for debugging/visibility)
+    if (cowResult.edr?.detected) {
+      const edrList = cowResult.edr.products.join(', ');
+      console.log(`[pi-var] Security software detected: ${edrList}`);
+
+      if (cowResult.edr.hasSlowCoWEDR && cowResult.performance && !cowResult.performance.fast) {
+        console.log(
+          `[pi-var] CoW performance impacted (${cowResult.performance.durationMs.toFixed(1)}ms). ` +
+            `Using ${type} instead.`
+        );
+      }
+    }
+  }
+
+  // Create variation based on type
+  switch (type) {
+    case 'cow': {
+      // CoW now returns git metadata when the source is a git repo
+      const cowResult = await createCoWVariation(sourcePath, variationPath, name);
+      branchName = cowResult.branchName;
+      mergeBaseCommit = cowResult.mergeBaseCommit;
+      break;
+    }
+    case 'worktree':
+      branchName = await createWorktreeVariation(
+        sourcePath,
+        variationPath,
+        name,
+        options.createBranch
+      );
+      break;
+    case 'copy':
+      await createCopyVariation(sourcePath, variationPath);
+      break;
+  }
+
+  // Ensure global gitignore ignores .pi/variations/ directories
+  ensureGlobalGitignore();
+
+  const now = new Date().toISOString();
+
+  return {
+    id,
+    name,
+    path: variationPath,
+    sourcePath,
+    type,
+    createdAt: now,
+    lastAccessed: now,
+    branchName,
+    mergeBaseCommit,
+  };
+}

package/extensions/pi-var/src/variation/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Variation module exports
+ */
+
+export { createVariation } from './create.js';
+export { removeVariation } from './remove.js';
+export { mergeVariation } from './merge/index.js';
+export { hasGitRepo } from './merge/strategy.js';
+export { detectCoWSupport } from '../cow/index.js';

package/extensions/pi-var/src/variation/merge/copy.ts

@@ -0,0 +1,151 @@
+/**
+ * Copy merge strategy (fallback for non-git sources)
+ *
+ * Backs up any source file that differs from the variation's version
+ * before overwriting, so data is never silently lost.
+ * For proper three-way merge with conflict detection, use git-backed
+ * CoW variations (source must be a git repo).
+ */
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import type { Variation, MergeOptions } from '../../types/index';
+
+/**
+ * Get list of files that should be merged (excluding certain directories)
+ */
+async function getFilesToMerge(variationPath: string, sourcePath: string): Promise<string[]> {
+  const files: string[] = [];
+  const excludePatterns = [
+    '.git',
+    '.pi/variations',
+    '.pi/merge-backup',
+    'node_modules',
+    '.next',
+    '.nuxt',
+    'target',
+    '.venv',
+    'venv',
+  ];
+
+  async function scan(dir: string, relativeDir: string) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const relativePath = relativeDir ? path.join(relativeDir, entry.name) : entry.name;
+      const fullPath = path.join(dir, entry.name);
+
+      // Check if this path should be excluded
+      if (excludePatterns.some((pattern) => relativePath.startsWith(pattern))) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        await scan(fullPath, relativePath);
+      } else {
+        files.push(relativePath);
+      }
+    }
+  }
+
+  await scan(variationPath, '');
+  return files;
+}
+
+/**
+ * Check if a source file differs from the variation's version.
+ * When they differ, backing up the source version prevents data loss
+ * regardless of which side changed.
+ */
+async function differsFromVariation(
+  relativePath: string,
+  variationPath: string,
+  sourcePath: string
+): Promise<boolean> {
+  const sourceFile = path.join(sourcePath, relativePath);
+  const variationFile = path.join(variationPath, relativePath);
+
+  try {
+    const [sourceContent, variationContent] = await Promise.all([
+      fs.readFile(sourceFile),
+      fs.readFile(variationFile),
+    ]);
+
+    // If files are identical, overwriting is a no-op
+    return !sourceContent.equals(variationContent);
+  } catch {
+    // One of the files doesn't exist — new file or deleted, no backup needed
+    return false;
+  }
+}
+
+/**
+ * Merge using direct file copy with backup protection
+ */
+export async function mergeWithCopy(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions
+): Promise<string> {
+  // Get list of files to merge
+  const files = await getFilesToMerge(variation.path, sourcePath);
+
+  // Find files where the source version differs from the variation
+  // (these will be overwritten — back them up to prevent data loss)
+  const overwrittenFiles: string[] = [];
+  const backupDir = path.join(sourcePath, '.pi', 'merge-backup', variation.name);
+
+  for (const relativePath of files) {
+    if (await differsFromVariation(relativePath, variation.path, sourcePath)) {
+      overwrittenFiles.push(relativePath);
+    }
+  }
+
+  if (options.dryRun) {
+    const fileList = files.map((f) => `  ${f}`).join('\n');
+    const overwrittenList = overwrittenFiles.length
+      ? `\n\n⚠ Source files that differ from variation (will be backed up before overwrite):\n${overwrittenFiles.map((f) => `  ${f}`).join('\n')}\n  → Backups saved to .pi/merge-backup/${variation.name}/`
+      : '';
+    return `Files that would be merged:\n${fileList}${overwrittenList}`;
+  }
+
+  // Back up source files that will be overwritten with different content
+  if (overwrittenFiles.length > 0) {
+    await fs.mkdir(backupDir, { recursive: true });
+
+    for (const relativePath of overwrittenFiles) {
+      const sourceFile = path.join(sourcePath, relativePath);
+      const backupFile = path.join(backupDir, relativePath);
+
+      try {
+        await fs.mkdir(path.dirname(backupFile), { recursive: true });
+        await fs.copyFile(sourceFile, backupFile);
+      } catch {
+        // Source file may not exist — skip backup
+      }
+    }
+  }
+
+  // Copy each file
+  for (const relativePath of files) {
+    const srcFile = path.join(variation.path, relativePath);
+    const destFile = path.join(sourcePath, relativePath);
+
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(destFile), { recursive: true });
+
+    // Copy file
+    await fs.copyFile(srcFile, destFile);
+  }
+
+  // Report overwritten files and backups
+  if (overwrittenFiles.length > 0) {
+    return (
+      `⚠ ${overwrittenFiles.length} source file(s) overwritten. ` +
+      `Originals backed up to ${backupDir}\n` +
+      `Overwritten files:\n${overwrittenFiles.map((f) => `  ${f}`).join('\n')}`
+    );
+  }
+
+  return '';
+}

package/extensions/pi-var/src/variation/merge/git.ts

@@ -0,0 +1,176 @@
+/**
+ * Git merge strategy for worktree and git-backed CoW variations
+ *
+ * Worktrees share the same .git as the source, so `git merge <branch>` works directly.
+ * CoW variations have their own .git (CoW-cloned from the source), so we add the
+ * variation as a temporary remote, fetch the branch, merge, and clean up.
+ *
+ * Both paths give proper three-way merge semantics with conflict detection,
+ * so merging Variation B after Variation A won't silently overwrite A's changes.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import type { Variation, MergeOptions } from '../../types/index';
+
+const execAsync = promisify(exec);
+
+/**
+ * Generate a temporary remote name for a CoW variation merge.
+ * Uses a pi-var- prefix to avoid conflicts with user-defined remotes.
+ */
+function tempRemoteName(variation: Variation): string {
+  // Sanitize the variation name for use as a git remote name
+  const safe = variation.name.replace(/[^a-zA-Z0-9-_]/g, '-');
+  return `pi-var-${safe}`;
+}
+
+/**
+ * Merge a CoW variation via remote fetch.
+ *
+ * Flow:
+ * 1. Commit any pending work in the variation
+ * 2. Add variation as a temporary remote to the source
+ * 3. Fetch the variation's branch
+ * 4. Merge with three-way merge
+ * 5. Clean up the temporary remote
+ */
+async function mergeCowViaRemote(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions
+): Promise<string> {
+  if (!variation.branchName) {
+    throw new Error('Cannot merge: CoW variation has no associated branch');
+  }
+
+  const remoteName = tempRemoteName(variation);
+
+  // 1. Commit any pending work in the variation so it's all captured
+  try {
+    await execAsync(`git -C "${variation.path}" add -A`);
+    // Use --allow-empty so this doesn't fail if there's nothing new to commit
+    await execAsync(
+      `git -C "${variation.path}" commit -m "variation work: ${variation.name}" --allow-empty`
+    );
+  } catch {
+    // Nothing to commit or commit failed (e.g. empty repo) — proceed with what we have
+  }
+
+  // 2. Add variation as a temporary remote
+  try {
+    await execAsync(`git -C "${sourcePath}" remote add "${remoteName}" "${variation.path}"`);
+  } catch {
+    // Remote might already exist from a failed previous merge — update the URL
+    try {
+      await execAsync(`git -C "${sourcePath}" remote set-url "${remoteName}" "${variation.path}"`);
+    } catch {
+      throw new Error(`Failed to add temporary remote ${remoteName}`);
+    }
+  }
+
+  try {
+    // 3. Fetch the variation's branch
+    await execAsync(`git -C "${sourcePath}" fetch "${remoteName}" "${variation.branchName}"`);
+
+    // 4. Get current branch in source
+    const { stdout: currentBranch } = await execAsync(
+      `git -C "${sourcePath}" branch --show-current`
+    );
+    const targetBranch = currentBranch.trim();
+
+    if (!targetBranch) {
+      throw new Error('Cannot merge: source is in detached HEAD state');
+    }
+
+    if (options.dryRun) {
+      // Show what would be merged
+      const { stdout } = await execAsync(
+        `git -C "${sourcePath}" diff "${targetBranch}...${remoteName}/${variation.branchName}" --stat`
+      );
+      return `Files that would be merged (via git three-way merge):\n${stdout}`;
+    }
+
+    // 5. Merge with three-way merge
+    try {
+      await execAsync(
+        `git -C "${sourcePath}" merge "${remoteName}/${variation.branchName}" --no-edit`
+      );
+      return '';
+    } catch (err) {
+      // Merge conflict — report clearly so the user can resolve
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Git merge conflict. Resolve conflicts in ${sourcePath} and commit, then run:\n` +
+          `  git -C "${sourcePath}" mergetool\n` +
+          `  git -C "${sourcePath}" commit\n\n` +
+          `Details: ${message}`
+      );
+    }
+  } finally {
+    // 6. Always clean up the temporary remote, even on failure
+    try {
+      await execAsync(`git -C "${sourcePath}" remote remove "${remoteName}"`);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Merge a worktree variation directly (branch is in the same repo).
+ */
+async function mergeWorktreeDirect(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions
+): Promise<string> {
+  if (!variation.branchName) {
+    throw new Error('Cannot merge: variation has no associated branch');
+  }
+
+  // Get current branch in source
+  const { stdout: currentBranch } = await execAsync(`git -C "${sourcePath}" branch --show-current`);
+  const targetBranch = currentBranch.trim();
+
+  if (!targetBranch) {
+    throw new Error('Cannot merge: source is in detached HEAD state');
+  }
+
+  if (options.dryRun) {
+    // Show what would be merged
+    const { stdout } = await execAsync(
+      `git -C "${sourcePath}" diff "${targetBranch}...${variation.branchName}" --stat`
+    );
+    return `Files that would be merged (via git three-way merge):\n${stdout}`;
+  }
+
+  // Merge the branch
+  try {
+    await execAsync(`git -C "${sourcePath}" merge "${variation.branchName}" --no-edit`);
+    return '';
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Git merge conflict. Resolve conflicts in ${sourcePath} and commit, then run:\n` +
+        `  git -C "${sourcePath}" mergetool\n` +
+        `  git -C "${sourcePath}" commit\n\n` +
+        `Details: ${message}`
+    );
+  }
+}
+
+/**
+ * Merge using git (for worktrees and git-backed CoW variations)
+ */
+export async function mergeWithGit(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions
+): Promise<string> {
+  if (variation.type === 'cow') {
+    return mergeCowViaRemote(variation, sourcePath, options);
+  }
+
+  return mergeWorktreeDirect(variation, sourcePath, options);
+}

package/extensions/pi-var/src/variation/merge/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Variation merge orchestration
+ */
+
+import type { Variation, MergeOptions } from '../../types/index';
+import { detectMergeStrategy } from './strategy';
+import { mergeWithGit } from './git';
+import { mergeWithRsync } from './rsync';
+import { mergeWithCopy } from './copy';
+
+/**
+ * Merge a variation back to source
+ */
+export async function mergeVariation(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions = {}
+): Promise<string> {
+  const strategy = options.strategy || 'auto';
+  const effectiveStrategy =
+    strategy === 'auto' ? await detectMergeStrategy(variation, sourcePath) : strategy;
+
+  let result = '';
+  switch (effectiveStrategy) {
+    case 'git':
+      result = await mergeWithGit(variation, sourcePath, options);
+      break;
+    case 'rsync':
+      result = await mergeWithRsync(variation, sourcePath, options);
+      break;
+    default:
+      result = await mergeWithCopy(variation, sourcePath, options);
+  }
+
+  return result;
+}

package/extensions/pi-var/src/variation/merge/rsync.ts

@@ -0,0 +1,74 @@
+/**
+ * Rsync merge strategy with backup protection
+ *
+ * Uses --backup to preserve overwritten source files, and --update
+ * to skip files where the source is newer than the variation.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import type { Variation, MergeOptions } from '../../types/index';
+
+const execAsync = promisify(exec);
+
+/**
+ * Merge using rsync with backup
+ */
+export async function mergeWithRsync(
+  variation: Variation,
+  sourcePath: string,
+  options: MergeOptions
+): Promise<string> {
+  const rsyncFlags = options.dryRun ? '-avn' : '-av';
+  const backupDir = path.join(sourcePath, '.pi', 'merge-backup', variation.name);
+
+  // Build exclude patterns for rsync
+  const excludes = [
+    '--exclude=.git',
+    '--exclude=.pi/variations',
+    '--exclude=.pi/merge-backup',
+    '--exclude=node_modules',
+    '--exclude=.next',
+    '--exclude=.nuxt',
+    '--exclude=target',
+    '--exclude=.venv',
+    '--exclude=venv',
+  ];
+
+  // --backup preserves overwritten source files
+  // --suffix labels them with the variation name
+  const backupFlags = options.dryRun
+    ? `--backup --backup-dir="${backupDir}"`
+    : `--backup --backup-dir="${backupDir}"`;
+
+  const cmd = `rsync ${rsyncFlags} ${backupFlags} ${excludes.join(' ')} "${variation.path}/" "${sourcePath}/"`;
+
+  if (options.dryRun) {
+    const { stdout } = await execAsync(cmd);
+    return `Files that would be merged (with backup of overwritten files):\n${stdout}`;
+  }
+
+  await execAsync(cmd);
+
+  // Check if backup dir has any files (indicating conflicts)
+  try {
+    const { stdout: backupList } = await execAsync(
+      `find "${backupDir}" -type f 2>/dev/null | head -20`
+    );
+    if (backupList.trim()) {
+      return (
+        `⚠ Some source files were overwritten. Backed up to ${backupDir}\n` +
+        `Overwritten files:\n${backupList
+          .trim()
+          .split('\n')
+          .map((f: string) => `  ${path.relative(backupDir, f)}`)
+          .join('\n')}`
+      );
+    }
+  } catch {
+    // No backup dir or empty
+  }
+
+  return '';
+}

package/extensions/pi-var/src/variation/merge/strategy.ts

@@ -0,0 +1,62 @@
+/**
+ * Merge strategy detection
+ *
+ * CoW variations with a git branch (created from a git repo source)
+ * use git merge for proper three-way merge semantics — just like worktrees.
+ * CoW variations without a branch (non-git source) fall back to rsync/copy.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import type { Variation } from '../../types/index.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * Check if a directory contains a git repository
+ */
+export async function hasGitRepo(checkPath: string): Promise<boolean> {
+  try {
+    const gitDir = (await import('path')).join(checkPath, '.git');
+    const { promises: fs } = await import('fs');
+    const stat = await fs.stat(gitDir);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the best merge strategy for a variation
+ *
+ * Priority:
+ * 1. git — for worktrees (branch in same repo) and git-backed CoW (branch in variation repo)
+ * 2. rsync — for non-git CoW/copy when rsync is available
+ * 3. copy — fallback
+ */
+export async function detectMergeStrategy(
+  variation: Variation,
+  sourcePath: string
+): Promise<'git' | 'rsync' | 'copy'> {
+  // Prefer git for worktrees (branch is in the same repo as source)
+  if (variation.type === 'worktree' && (await hasGitRepo(sourcePath))) {
+    return 'git';
+  }
+
+  // Prefer git for CoW variations that have a branch (source was a git repo)
+  // The branch is in the variation's own .git, so we merge via remote fetch.
+  if (variation.type === 'cow' && variation.branchName && (await hasGitRepo(sourcePath))) {
+    return 'git';
+  }
+
+  // Check for rsync
+  try {
+    await execAsync('which rsync');
+    return 'rsync';
+  } catch {
+    // rsync not available
+  }
+
+  // Fall back to copy
+  return 'copy';
+}

package/extensions/pi-var/src/variation/paths.ts

@@ -0,0 +1,26 @@
+/**
+ * Variation name and ID utilities
+ */
+
+import * as crypto from 'crypto';
+
+/**
+ * Get the project name from a path
+ */
+export function getProjectName(sourcePath: string): string {
+  return sourcePath.split(/[/\\]/).pop() || 'project';
+}
+
+/**
+ * Generate a short hash for the project path
+ */
+export function getProjectHash(sourcePath: string): string {
+  return crypto.createHash('sha256').update(sourcePath).digest('hex').slice(0, 8);
+}
+
+/**
+ * Generate a unique variation ID
+ */
+export function generateVariationId(): string {
+  return `var-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}