pi-var 1.0.1

package/extensions/pi-var/__tests__/unit/variations.test.ts

@@ -0,0 +1,352 @@
+/**
+ * Unit tests for variation management utilities
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import {
+  detectCoWSupport,
+  hasGitRepo,
+  createVariation,
+  removeVariation,
+  mergeVariation,
+} from '../../src/variation/index';
+import type { Variation } from '../../src/types/index';
+
+// Helper to create a temporary test directory
+async function createTempDir(prefix: string): Promise<string> {
+  const tmpDir = os.tmpdir();
+  const randomId = crypto.randomBytes(4).toString('hex');
+  const dir = path.join(tmpDir, `${prefix}-${randomId}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+// Helper to cleanup a directory
+async function cleanupDir(dir: string): Promise<void> {
+  try {
+    await fs.rm(dir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+describe('detectCoWSupport', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await createTempDir('cow-test');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(testDir);
+  });
+
+  it('should return a result object with supported boolean', async () => {
+    const result = await detectCoWSupport(testDir);
+
+    expect(result).toHaveProperty('supported');
+    expect(typeof result.supported).toBe('boolean');
+  });
+
+  it('should return method when CoW is supported', async () => {
+    const result = await detectCoWSupport(testDir);
+
+    if (result.supported) {
+      expect(result.method).toBeDefined();
+      expect(['clonefile', 'reflink']).toContain(result.method);
+    }
+  });
+
+  it('should not leave test files behind', async () => {
+    const filesBefore = await fs.readdir(testDir).catch(() => []);
+
+    await detectCoWSupport(testDir);
+
+    const filesAfter = await fs.readdir(testDir).catch(() => []);
+
+    // Should only have files we created, no cow-test files
+    const cowTestFiles = filesAfter.filter(
+      (f) => f.includes('cow-test') || f.includes('cow-clone')
+    );
+    expect(cowTestFiles).toHaveLength(0);
+  });
+});
+
+describe('hasGitRepo', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await createTempDir('git-test');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(testDir);
+  });
+
+  it('should return false for non-git directory', async () => {
+    const result = await hasGitRepo(testDir);
+    expect(result).toBe(false);
+  });
+
+  it('should return true for git directory', async () => {
+    // Initialize git repo
+    await fs.mkdir(path.join(testDir, '.git'), { recursive: true });
+    await fs.writeFile(path.join(testDir, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+
+    const result = await hasGitRepo(testDir);
+    expect(result).toBe(true);
+  });
+
+  it('should return false for non-existent path', async () => {
+    const nonExistent = path.join(testDir, 'does-not-exist');
+    const result = await hasGitRepo(nonExistent);
+    expect(result).toBe(false);
+  });
+});
+
+describe('createVariation', () => {
+  let sourceDir: string;
+  let variationsBase: string;
+
+  beforeEach(async () => {
+    sourceDir = await createTempDir('source');
+
+    // Create some test files
+    await fs.writeFile(path.join(sourceDir, 'package.json'), JSON.stringify({ name: 'test' }));
+    await fs.mkdir(path.join(sourceDir, 'src'), { recursive: true });
+    await fs.writeFile(path.join(sourceDir, 'src', 'index'), 'console.log("hello");');
+
+    // Create .pi directory structure
+    variationsBase = path.join(sourceDir, '.pi', 'variations');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(sourceDir);
+  });
+
+  it('should create a variation with auto-generated name', async () => {
+    const variation = await createVariation(sourceDir);
+
+    expect(variation).toHaveProperty('id');
+    expect(variation).toHaveProperty('name');
+    expect(variation).toHaveProperty('path');
+    expect(variation).toHaveProperty('sourcePath', sourceDir);
+    expect(variation).toHaveProperty('type');
+    expect(variation).toHaveProperty('createdAt');
+    expect(variation).toHaveProperty('lastAccessed');
+
+    // Verify the directory was created
+    const stats = await fs.stat(variation.path);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  it('should create a variation with specified name', async () => {
+    const variation = await createVariation(sourceDir, { name: 'my-variation' });
+
+    expect(variation.name).toBe('my-variation');
+    expect(variation.path).toContain('my-variation');
+  });
+
+  it('should throw error if variation already exists', async () => {
+    await createVariation(sourceDir, { name: 'duplicate' });
+
+    await expect(createVariation(sourceDir, { name: 'duplicate' })).rejects.toThrow(
+      /already exists/
+    );
+  });
+
+  it('should create copy variation when type is explicitly set', async () => {
+    const variation = await createVariation(sourceDir, {
+      name: 'copy-test',
+      type: 'copy',
+    });
+
+    expect(variation.type).toBe('copy');
+
+    // Verify files were copied
+    const pkgJson = await fs.readFile(path.join(variation.path, 'package.json'), 'utf-8');
+    expect(JSON.parse(pkgJson).name).toBe('test');
+  });
+
+  it('should not copy nested .pi/variations directory', async () => {
+    // Create a pre-existing variation
+    await createVariation(sourceDir, { name: 'existing' });
+
+    // Create new variation - should not include the existing variation's .pi folder
+    const newVariation = await createVariation(sourceDir, {
+      name: 'new-var',
+      type: 'copy',
+    });
+
+    // The new variation should not have the existing variation inside it
+    const nestedVarPath = path.join(newVariation.path, '.pi', 'variations', 'existing');
+    await expect(fs.access(nestedVarPath)).rejects.toThrow();
+  });
+});
+
+describe('removeVariation', () => {
+  let sourceDir: string;
+
+  beforeEach(async () => {
+    sourceDir = await createTempDir('source');
+    await fs.writeFile(path.join(sourceDir, 'file.txt'), 'content');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(sourceDir);
+  });
+
+  it('should remove a copy variation', async () => {
+    const variation = await createVariation(sourceDir, {
+      name: 'to-remove',
+      type: 'copy',
+    });
+
+    // Verify it exists
+    await fs.access(variation.path);
+
+    // Remove it
+    await removeVariation(variation);
+
+    // Verify it's gone
+    await expect(fs.access(variation.path)).rejects.toThrow();
+  });
+
+  it('should clean up empty parent directories', async () => {
+    const variation = await createVariation(sourceDir, {
+      name: 'cleanup-test',
+      type: 'copy',
+    });
+
+    const variationsDir = path.dirname(variation.path);
+    const piDir = path.dirname(variationsDir);
+
+    await removeVariation(variation);
+
+    // If this was the only variation, .pi/variations should be cleaned up
+    try {
+      await fs.access(variationsDir);
+      // If it still exists, that's fine - other variations may exist
+    } catch {
+      // Was cleaned up as expected
+    }
+  });
+});
+
+describe('mergeVariation', () => {
+  let sourceDir: string;
+  let variation: Variation;
+
+  beforeEach(async () => {
+    sourceDir = await createTempDir('source');
+
+    // Create source files
+    await fs.writeFile(path.join(sourceDir, 'file.txt'), 'original');
+    await fs.mkdir(path.join(sourceDir, 'src'), { recursive: true });
+    await fs.writeFile(path.join(sourceDir, 'src', 'app'), '// original');
+
+    // Create variation with changes
+    variation = await createVariation(sourceDir, {
+      name: 'to-merge',
+      type: 'copy',
+    });
+
+    // Modify files in variation
+    await fs.writeFile(path.join(variation.path, 'new-file.txt'), 'new content');
+    await fs.writeFile(path.join(variation.path, 'src', 'app'), '// modified');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(sourceDir);
+  });
+
+  it('should merge new files to source', async () => {
+    // New file should not exist in source yet
+    await expect(fs.access(path.join(sourceDir, 'new-file.txt'))).rejects.toThrow();
+
+    await mergeVariation(variation, sourceDir);
+
+    // New file should now exist
+    const content = await fs.readFile(path.join(sourceDir, 'new-file.txt'), 'utf-8');
+    expect(content).toBe('new content');
+  });
+
+  it('should merge modified files to source', async () => {
+    const original = await fs.readFile(path.join(sourceDir, 'src', 'app'), 'utf-8');
+    expect(original).toBe('// original');
+
+    // Force copy strategy to avoid rsync issues in test environment
+    await mergeVariation(variation, sourceDir, { strategy: 'copy' });
+
+    const merged = await fs.readFile(path.join(sourceDir, 'src', 'app'), 'utf-8');
+    expect(merged).toBe('// modified');
+  });
+
+  it('should keep variation after merge', async () => {
+    const variationPath = variation.path;
+
+    await mergeVariation(variation, sourceDir);
+
+    // Variation should still exist
+    const stats = await fs.stat(variationPath);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  it('should support dry run mode', async () => {
+    const variationPath = variation.path;
+
+    await mergeVariation(variation, sourceDir, { dryRun: true });
+
+    // Variation should still exist
+    const stats = await fs.stat(variationPath);
+    expect(stats.isDirectory()).toBe(true);
+
+    // But files should not have been merged
+    await expect(fs.access(path.join(sourceDir, 'new-file.txt'))).rejects.toThrow();
+  });
+});
+
+describe('variation type selection', () => {
+  let sourceDir: string;
+
+  beforeEach(async () => {
+    sourceDir = await createTempDir('source');
+    await fs.writeFile(path.join(sourceDir, 'file.txt'), 'content');
+  });
+
+  afterEach(async () => {
+    await cleanupDir(sourceDir);
+  });
+
+  it('should auto-select appropriate type', async () => {
+    const variation = await createVariation(sourceDir);
+
+    // Type should be one of the valid types
+    expect(['cow', 'worktree', 'copy']).toContain(variation.type);
+  });
+
+  it('should allow forcing specific type', async () => {
+    const copyVar = await createVariation(sourceDir, {
+      name: 'forced-copy',
+      type: 'copy',
+    });
+    expect(copyVar.type).toBe('copy');
+
+    // Create another source dir for next test
+    const anotherSource = await createTempDir('another-source');
+    await fs.writeFile(path.join(anotherSource, 'file.txt'), 'content');
+
+    const cowVar = await createVariation(anotherSource, {
+      name: 'forced-cow',
+      type: 'cow',
+    });
+    // May fall back to copy if CoW not supported
+    expect(['cow', 'copy']).toContain(cowVar.type);
+
+    await cleanupDir(anotherSource);
+  });
+});

package/extensions/pi-var/index.ts

@@ -0,0 +1,111 @@
+/**
+ * pi-var — Copy-on-write variations extension (autoregressive)
+ *
+ * AI-driven variation management:
+ * - create_variation tool — AI creates variations automatically
+ * - /var command — argument-free status and manual override
+ * - File redirection — transparent read/edit/write to active variation
+ * - Environment sync — copy .env, symlink node_modules
+ *
+ * Port isolation is handled by the AI via bash (portless), not extension code.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from './src/types/index';
+import { generateVariationName } from './src/utils/names';
+import { getSessionKey, createRuntimeStore } from './src/state/index';
+import { registerVarCommand } from './src/tools/command/index';
+import { registerRedirectedTools } from './src/tools/redirect/index';
+import { registerCreateVariationTool } from './src/tools/variation/create';
+import { registerMergeVariationTool } from './src/tools/variation/merge';
+import { detectVariationContext } from './src/environment/index';
+import { DEFAULT_CONFIG } from './src/config';
+
+export default function piVarExtension(pi: ExtensionAPI) {
+  // Session-scoped runtime store
+  const runtimeStore = createRuntimeStore();
+  const getRuntime = (ctx: ExtensionContext): VarRuntime => runtimeStore.ensure(getSessionKey(ctx));
+  const persistState = (ctx: ExtensionContext): void =>
+    runtimeStore.persistState(getSessionKey(ctx), pi);
+
+  // Register /var command (argument-free, status/overview)
+  registerVarCommand(pi, { getRuntime, pi, runtimeStore });
+
+  // Register redirected tools (read, edit, write, bash) - overrides built-ins when variation is active
+  registerRedirectedTools(pi, getRuntime);
+
+  // Register variation management tools
+  registerCreateVariationTool(pi, getRuntime);
+  registerMergeVariationTool(pi, getRuntime, persistState);
+
+  // Session lifecycle
+  pi.on('session_start', async (_event, ctx) => {
+    const sessionKey = getSessionKey(ctx);
+
+    // First ensure runtime exists, then restore from session
+    runtimeStore.ensure(sessionKey);
+    runtimeStore.restoreState(sessionKey, ctx.sessionManager);
+
+    const runtime = getRuntime(ctx);
+
+    // Detect if we're inside a variation directory
+    const context = detectVariationContext(ctx.cwd);
+    if (context.inVariation && context.variationId) {
+      // Reconnect to existing variation
+      const existing = runtime.state.variations.find((v) => v.id === context.variationId);
+      if (existing) {
+        runtime.state.activeVariationId = existing.id;
+        ctx.ui.notify(`Reconnected to variation: ${existing.name}`, 'info');
+        // Persist the reconnection
+        runtimeStore.persistState(sessionKey, pi);
+      }
+    }
+  });
+
+  // System prompt extension when in variation
+  pi.on('before_agent_start', async (event, ctx) => {
+    const runtime = getRuntime(ctx);
+    if (!runtime.state.activeVariationId) return;
+
+    const variation = runtime.state.variations.find(
+      (v) => v.id === runtime.state.activeVariationId
+    );
+    if (!variation) return;
+
+    const typeLabel =
+      variation.type === 'cow'
+        ? 'Copy-on-Write (APFS clonefile)'
+        : variation.type === 'worktree'
+          ? 'Git worktree'
+          : 'Full copy';
+
+    const mergeInfo = variation.branchName
+      ? '\n- Merge: Use merge_variation for git three-way merge (conflict detection enabled)'
+      : '';
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `
+
+## Active Variation: "${variation.name}"
+You are working in an isolated variation. All operations automatically redirect:
+
+**File Operations:** read, edit, write → variation directory (${variation.path})
+**Shell Commands:** bash → executes in variation directory with cwd=${variation.path}
+**Environment:** PI_VARIATION=${variation.name}, PI_VARIATION_PATH, PI_SOURCE_PATH set
+
+- Source: ${variation.sourcePath}
+- Variation: ${variation.path}
+- Type: ${typeLabel}${mergeInfo}
+
+Use tools normally - the extension handles all redirection. When finished, use merge_variation to merge back to source.
+`,
+    };
+  });
+
+  // Session end - persist final state
+  pi.on('session_shutdown', async (_event, ctx) => {
+    runtimeStore.persistState(getSessionKey(ctx), pi);
+  });
+}

package/extensions/pi-var/src/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Extension configuration
+ */
+
+export const DEFAULT_CONFIG = {
+  copy: [
+    '.env',
+    '.env.*',
+    '.envrc',
+    '.npmrc',
+    '.yarnrc',
+    '.yarnrc.yml',
+    '.tool-versions',
+    '.node-version',
+    '.python-version',
+    'docker-compose.override.yml',
+  ],
+  symlink: [
+    'node_modules',
+    '.next',
+    '.nuxt',
+    '.angular',
+    '.turbo',
+    'target',
+    '.venv',
+    'venv',
+    'vendor',
+  ],
+  postCreate: [],
+};

package/extensions/pi-var/src/cow/clone.ts

@@ -0,0 +1,46 @@
+/**
+ * Low-level CoW clone using platform-specific methods.
+ * This is the filesystem-level clone only — no git branch setup.
+ * For the full variation creation with git branch, use variation/create-cow.ts.
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { promises as fs } from 'fs';
+import { detectCoWSupport } from './detection';
+
+const execAsync = promisify(exec);
+
+/**
+ * Create a CoW clone using platform-specific methods.
+ * Copies the entire source directory (including .git if present)
+ * using copy-on-write for zero-additional-space clones.
+ */
+export async function createCoWClone(sourcePath: string, destPath: string): Promise<void> {
+  const platform = os.platform();
+  const cowSupport = await detectCoWSupport(path.dirname(destPath));
+
+  if (!cowSupport.supported) {
+    throw new Error('CoW not supported on this platform/filesystem');
+  }
+
+  if (platform === 'darwin' && cowSupport.method === 'clonefile') {
+    // macOS: Use cp -c for clonefile
+    await execAsync(`cp -c -R "${sourcePath}" "${destPath}"`);
+  } else if (platform === 'linux' && cowSupport.method === 'reflink') {
+    // Linux: Use cp --reflink=auto
+    await execAsync(`cp -a --reflink=auto "${sourcePath}" "${destPath}"`);
+  } else {
+    throw new Error(`Unsupported CoW method: ${cowSupport.method}`);
+  }
+
+  // Remove the .pi/variations directory from the clone to avoid recursion
+  const nestedVariations = path.join(destPath, '.pi', 'variations');
+  try {
+    await fs.rm(nestedVariations, { recursive: true, force: true });
+  } catch {
+    // Ignore if doesn't exist
+  }
+}