pi-var 1.0.1

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

@@ -0,0 +1,108 @@
+/**
+ * create_variation tool registration
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import type { VarRuntime } from '../../types/index';
+import { createVariation } from '../../variation/create';
+import { setupVariationEnvironment, DEFAULT_CONFIG } from '../../environment/index';
+import { generateVariationName } from '../../utils/names';
+
+export function registerCreateVariationTool(
+  pi: ExtensionAPI,
+  getRuntime: (ctx: ExtensionContext) => VarRuntime
+): void {
+  pi.registerTool({
+    name: 'create_variation',
+    label: 'Create Variation',
+    description:
+      'Create a copy-on-write variation for isolated development work. ' +
+      'Auto-generates a semantic name from the purpose. ' +
+      'Auto-detects best method: CoW (APFS clonefile/Linux reflink) > Git worktree > Full copy. ' +
+      'All file operations automatically redirect to the variation. ' +
+      'For port isolation (dev servers), run `npx portless --json` via bash and set PORT from result.',
+    parameters: Type.Object({
+      purpose: Type.String({
+        description:
+          'Brief description of what this variation is for (e.g., "fix auth bug", "experiment with new UI"). ' +
+          'Used to auto-generate a semantic name.',
+      }),
+      type: Type.Optional(
+        Type.Union([Type.Literal('cow'), Type.Literal('worktree'), Type.Literal('copy')], {
+          description:
+            'Optional: Force specific creation method. If omitted, auto-detects best available.',
+        })
+      ),
+      createBranch: Type.Optional(
+        Type.Boolean({
+          default: false,
+          description: 'For worktrees: create a git branch (var/<name>) for this variation.',
+        })
+      ),
+    }),
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const text = (msg: string) => ({
+        content: [{ type: 'text' as const, text: msg }],
+        details: undefined,
+      });
+
+      const runtime = getRuntime(ctx);
+
+      // Auto-generate name from purpose
+      const semanticName = params.purpose
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 30);
+      const variationName = semanticName || generateVariationName();
+
+      // Check for existing
+      const existing = runtime.state.variations.find((v) => v.name === variationName);
+      if (existing) {
+        return text(
+          `Variation "${variationName}" already exists. ` +
+            `Switch to it with the variation context, or create with a different purpose.`
+        );
+      }
+
+      try {
+        // Create variation
+        const variation = await createVariation(ctx.cwd, {
+          name: variationName,
+          type: params.type,
+          createBranch: params.createBranch,
+        });
+
+        // Setup environment
+        await setupVariationEnvironment(ctx.cwd, variation.path, DEFAULT_CONFIG);
+
+        // Add to runtime and activate
+        runtime.state.variations.push(variation);
+        runtime.state.activeVariationId = variation.id;
+
+        const typeLabel =
+          variation.type === 'cow'
+            ? 'CoW clone'
+            : variation.type === 'worktree'
+              ? 'Git worktree'
+              : 'Full copy';
+
+        const branchInfo = variation.branchName
+          ? `\nBranch: ${variation.branchName}` +
+            (variation.mergeBaseCommit ? ` (base: ${variation.mergeBaseCommit.slice(0, 8)})` : '')
+          : '';
+
+        return text(
+          `Created ${typeLabel} variation "${variation.name}" for: ${params.purpose}\n` +
+            `Path: ${variation.path}\n\n` +
+            `All file operations now redirect to this variation.` +
+            branchInfo
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return text(`Failed to create variation: ${message}`);
+      }
+    },
+  });
+}

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

@@ -0,0 +1,80 @@
+/**
+ * merge_variation tool registration
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import type { VarRuntime } from '../../types/index';
+import { mergeVariation } from '../../variation/merge/index.js';
+
+export function registerMergeVariationTool(
+  pi: ExtensionAPI,
+  getRuntime: (ctx: ExtensionContext) => VarRuntime,
+  persistState: (ctx: ExtensionContext) => void
+): void {
+  pi.registerTool({
+    name: 'merge_variation',
+    label: 'Merge Variation',
+    description:
+      'Merge changes from the current variation back to the source directory. ' +
+      'Auto-selects merge strategy: git (for worktrees) > rsync > copy. ' +
+      'Variations are never deleted automatically. Use /var clean to remove old variations.',
+    parameters: Type.Object({
+      dryRun: Type.Optional(
+        Type.Boolean({
+          default: false,
+          description: 'Preview what would be merged without applying changes.',
+        })
+      ),
+    }),
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const text = (msg: string) => ({
+        content: [{ type: 'text' as const, text: msg }],
+        details: undefined,
+      });
+
+      const runtime = getRuntime(ctx);
+      const activeId = runtime.state.activeVariationId;
+
+      if (!activeId) {
+        return text('No active variation to merge. Create one with create_variation first.');
+      }
+
+      const variation = runtime.state.variations.find((v) => v.id === activeId);
+      if (!variation) {
+        return text('Active variation not found in state. This is a bug.');
+      }
+
+      try {
+        const dryRunOutput = await mergeVariation(variation, ctx.cwd, {
+          dryRun: params.dryRun,
+        });
+
+        // Deactivate variation after successful merge (not dry-run)
+        if (!params.dryRun) {
+          runtime.state.activeVariationId = null;
+          ctx.ui.setStatus('pi-var', '');
+        }
+
+        // Persist state to session
+        persistState(ctx);
+
+        const action = params.dryRun ? 'Would merge' : 'Merged';
+        const strategyUsed =
+          variation.type === 'cow' && variation.branchName
+            ? ' (via git three-way merge)'
+            : variation.type === 'worktree'
+              ? ' (via git merge)'
+              : '';
+        const output = dryRunOutput ? `\n\n${dryRunOutput}` : '';
+        const deactivated = !params.dryRun ? ' Now back in source directory.' : '';
+        return text(
+          `${action} variation "${variation.name}" to source${strategyUsed}.${deactivated}${output}`
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return text(`Failed to merge variation: ${message}`);
+      }
+    },
+  });
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Core type definitions for pi-var extension
+ */
+
+/**
+ * EDR detection result
+ */
+export interface EDRDetectionResult {
+  /** Whether any EDR was detected */
+  detected: boolean;
+  /** List of detected EDR process names */
+  found: string[];
+  /** Detailed info about each detected EDR */
+  details: EDRDetails[];
+}
+
+/**
+ * Detailed information about a detected EDR
+ */
+export interface EDRDetails {
+  /** Process name */
+  process: string;
+  /** EDR vendor/product name */
+  product: string;
+  /** Whether this EDR is known to significantly impact CoW operations */
+  knownSlowCoW: boolean;
+}
+
+/**
+ * CoW detection result with EDR awareness
+ */
+export interface CoWDetectionResult {
+  /** Whether CoW is supported on this platform/filesystem */
+  supported: boolean;
+  /** CoW method if supported */
+  method?: 'clonefile' | 'reflink';
+  /** EDR detection results */
+  edr?: {
+    /** Whether any EDR was detected */
+    detected: boolean;
+    /** List of detected EDR products */
+    products: string[];
+    /** Whether any detected EDR is known to slow CoW operations */
+    hasSlowCoWEDR: boolean;
+  };
+  /** Performance test results */
+  performance?: {
+    /** Whether CoW performed fast enough to be usable */
+    fast: boolean;
+    /** Average time in ms for CoW operations */
+    durationMs: number;
+    /** Number of timing samples collected */
+    samples?: number;
+    /** Maximum duration observed (helps detect spikes) */
+    maxDurationMs?: number;
+    /** Confidence level in the timing measurement */
+    confidence?: 'high' | 'medium' | 'low';
+  };
+  /** Recommended variation type based on CoW support and EDR presence */
+  recommendedType: 'cow' | 'worktree' | 'copy';
+}
+
+export type VariationType = 'cow' | 'worktree' | 'copy';
+
+export interface Variation {
+  /** Unique identifier */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Absolute path to variation directory */
+  path: string;
+  /** Absolute path to source directory */
+  sourcePath: string;
+  /** Creation method used */
+  type: VariationType;
+  /** ISO timestamp when created */
+  createdAt: string;
+  /** Last accessed timestamp */
+  lastAccessed: string;
+  /** Git branch name (for worktrees and git-backed CoW variations) */
+  branchName?: string;
+  /** The commit SHA the variation was branched from, used as merge base for three-way merge */
+  mergeBaseCommit?: string;
+}
+
+export interface VarState {
+  /** Currently active variation ID, null if in source */
+  activeVariationId: string | null;
+  /** All variations for this session */
+  variations: Variation[];
+  /** Session ID for isolation */
+  sessionId: string;
+}
+
+export interface VarConfig {
+  /** Files to copy from source to variation */
+  copy: string[];
+  /** Directories to symlink (saves space) */
+  symlink: string[];
+  /** Commands to run after variation creation */
+  postCreate: string[];
+}
+
+export interface VarRuntime {
+  /** In-memory state (per-session) */
+  state: VarState;
+  /** Last time the state was persisted to JSONL */
+  lastPersisted: number;
+}
+
+export interface CreateVariationOptions {
+  /** Variation name (auto-generated if not provided) */
+  name?: string;
+  /** Force specific type */
+  type?: VariationType;
+  /** Create git branch */
+  createBranch?: boolean;
+}
+
+export interface MergeOptions {
+  /** Dry run - show what would change */
+  dryRun?: boolean;
+  /** Merge strategy: 'auto' | 'git' | 'rsync' | 'copy' */
+  strategy?: 'auto' | 'git' | 'rsync' | 'copy';
+}
+
+/** Context detection result */
+export interface VariationContext {
+  /** True if currently inside a variation directory */
+  inVariation: boolean;
+  /** Variation ID (if in variation) */
+  variationId: string | null;
+  /** Variation name (if in variation) */
+  variationName: string | null;
+  /** Current variation path (if in variation) */
+  variationPath: string | null;
+  /** Source directory path */
+  sourcePath: string;
+}

package/extensions/pi-var/src/utils/names.ts

@@ -0,0 +1,120 @@
+/**
+ * Name generation utilities for variations
+ */
+
+/**
+ * List of adjectives for variation name generation
+ */
+const ADJECTIVES: readonly string[] = [
+  'swift',
+  'bright',
+  'calm',
+  'fierce',
+  'gentle',
+  'bold',
+  'quiet',
+  'wild',
+  'purple',
+  'crimson',
+  'azure',
+  'golden',
+  'silver',
+  'amber',
+  'emerald',
+  'brave',
+  'clever',
+  'happy',
+  'noble',
+  'proud',
+  'sunny',
+  'vivid',
+  'warm',
+  'cool',
+  'deep',
+  'high',
+  'light',
+  'rapid',
+  'smooth',
+  'strong',
+];
+
+/**
+ * List of nouns for variation name generation
+ */
+const NOUNS: readonly string[] = [
+  'river',
+  'mountain',
+  'forest',
+  'ocean',
+  'meadow',
+  'valley',
+  'canyon',
+  'thunder',
+  'lightning',
+  'sunrise',
+  'sunset',
+  'storm',
+  'breeze',
+  'flame',
+  'octopus',
+  'falcon',
+  'tiger',
+  'wolf',
+  'eagle',
+  'dolphin',
+  'whale',
+  'bear',
+  'comet',
+  'galaxy',
+  'nebula',
+  'planet',
+  'star',
+  'moon',
+  'nova',
+  'quasar',
+  'shadow',
+  'echo',
+  'dream',
+  'spirit',
+  'phantom',
+  'mirage',
+  'legend',
+  'myth',
+];
+
+/**
+ * Generate a unique variation ID
+ * Uses crypto.randomUUID() when available, falls back to timestamp + random
+ * @returns Unique identifier string
+ */
+export function generateVariationId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  // Fallback: timestamp + random hex string
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `${timestamp}-${random}`;
+}
+
+/**
+ * Generate a random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer in range [min, max]
+ */
+function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Generate a human-readable variation name
+ * Format: adjective-noun (e.g., "purple-octopus", "swift-river")
+ * @returns Generated variation name
+ */
+export function generateVariationName(): string {
+  const adjective = ADJECTIVES[randomInt(0, ADJECTIVES.length - 1)];
+  const noun = NOUNS[randomInt(0, NOUNS.length - 1)];
+  return `${adjective}-${noun}`;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Full copy variation creation
+ */
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+/**
+ * Create a full copy variation
+ */
+export async function createCopyVariation(sourcePath: string, destPath: string): Promise<void> {
+  // Create destination directory first
+  await fs.mkdir(destPath, { recursive: true });
+
+  // Get all entries from source
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(sourcePath, entry.name);
+    const destFilePath = path.join(destPath, entry.name);
+
+    // Skip the .pi directory to avoid recursion
+    if (entry.name === '.pi') {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      // Recursively copy subdirectory
+      await createCopyVariation(srcPath, destFilePath);
+    } else {
+      // Copy file
+      await fs.copyFile(srcPath, destFilePath);
+    }
+  }
+}

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

@@ -0,0 +1,81 @@
+/**
+ * CoW variation creation with git branch initialization
+ *
+ * After the CoW clone (delegated to cow/clone.ts), if the source is a git repo,
+ * we create a branch inside the variation and commit any uncommitted changes
+ * from the source. This gives CoW variations a proper merge base for three-way
+ * git merge, solving the "overwrite previous merges" and "dirty base" problems.
+ */
+
+import * as path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { promises as fs } from 'fs';
+import { createCoWClone } from '../cow/clone';
+
+const execAsync = promisify(exec);
+
+/** Result of CoW variation creation with optional git metadata */
+interface CoWCreationResult {
+  /** Git branch name, if variation was initialized in a git repo */
+  branchName?: string;
+  /** The commit SHA the branch was created from (merge base) */
+  mergeBaseCommit?: string;
+}
+
+/**
+ * Create a CoW variation: clone the source, then initialize a git branch.
+ *
+ * The CoW clone is delegated to cow/clone.ts (platform-specific cp -c / --reflink).
+ * Then, if .git exists in the clone, we create a var/<name> branch and commit
+ * any uncommitted changes from the source as an initial commit.
+ */
+export async function createCoWVariation(
+  sourcePath: string,
+  destPath: string,
+  variationName: string
+): Promise<CoWCreationResult> {
+  // 1. CoW clone (platform-specific, includes .git if present)
+  await createCoWClone(sourcePath, destPath);
+
+  // 2. Initialize git branch in the variation (if .git exists)
+  // This gives us proper merge semantics — the branch creates a named ref
+  // and the initial commit captures the source's working tree state at
+  // creation time (including any uncommitted changes).
+  const result: CoWCreationResult = {};
+
+  try {
+    const gitDir = path.join(destPath, '.git');
+    await fs.access(gitDir);
+
+    // Record the current HEAD commit as the merge base
+    // This is the commit BEFORE any variation-specific changes,
+    // so it serves as the common ancestor for three-way merge.
+    const { stdout: headCommit } = await execAsync(`git -C "${destPath}" rev-parse HEAD`);
+    result.mergeBaseCommit = headCommit.trim();
+
+    // Create a named branch in the variation's git repo
+    const branchName = `var/${variationName}`;
+    await execAsync(`git -C "${destPath}" checkout -b "${branchName}"`);
+    result.branchName = branchName;
+
+    // Capture any uncommitted changes from the source as an initial commit.
+    // This records "what the source looked like" at creation time —
+    // including dirty working tree files — so that the merge base is
+    // accurate even if the source had uncommitted changes.
+    try {
+      await execAsync(`git -C "${destPath}" add -A`);
+      await execAsync(
+        `git -C "${destPath}" commit -m "variation base: ${variationName}" --allow-empty`
+      );
+    } catch {
+      // Nothing to commit — source was clean. The branch already points
+      // to the right commit, so this is fine.
+    }
+  } catch {
+    // No .git directory — source is not a git repo.
+    // Skip git branch setup; merge will fall back to rsync/copy.
+  }
+
+  return result;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Git worktree variation creation
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Create a git worktree variation
+ */
+export async function createWorktreeVariation(
+  sourcePath: string,
+  destPath: string,
+  name: string,
+  createBranch?: boolean
+): Promise<string | undefined> {
+  const branchName = createBranch ? `var/${name}` : undefined;
+
+  if (branchName) {
+    // Create new branch and worktree
+    await execAsync(`git -C "${sourcePath}" branch "${branchName}"`);
+    await execAsync(`git -C "${sourcePath}" worktree add "${destPath}" "${branchName}"`);
+  } else {
+    // Add worktree from current HEAD (detached)
+    await execAsync(`git -C "${sourcePath}" worktree add --detach "${destPath}"`);
+  }
+
+  return branchName;
+}