pi-var 1.0.1

package/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+github: monotykamary
+ko_fi: monotykamary
+buy_me_a_coffee: monotykamary
+polar: monotykamary

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/README.md

@@ -0,0 +1,240 @@
+<div align="center">
+
+# 🌿 pi-var
+
+**AI-driven copy-on-write variations for [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_Work on multiple features simultaneously with isolated workspaces — automatically._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+---
+
+## Philosophy: The AI Does It
+
+Traditional variation management requires you to:
+
+- Name the variation
+- Remember to switch contexts
+- Manually merge and clean up
+
+**pi-var** removes all of that. The AI detects when isolated work is needed and handles everything:
+
+- Creates variations with semantic names
+- Redirects all file operations automatically
+- Suggests merge when work is complete
+
+You just say what you want. The AI manages the workspace.
+
+---
+
+## How It Works
+
+```
+User: "Work on the new dashboard feature while I fix this bug in main"
+         │
+         ▼
+   ┌─────────────┐
+   │  pi-var     │  ← AI decides isolation is needed
+   └──────┬──────┘
+          │
+    ┌─────┴─────┐
+    ▼           ▼
+┌───────┐   ┌─────────┐
+│ main  │   │ 🌿 dash │  ← CoW clone (instant, zero copy)
+│ (src) │   │  (src') │
+└───┬───┘   └────┬────┘
+    │            │
+    │ bug fix    │ dashboard feature
+    │            │
+    ▼            ▼
+  merge ◄──────┘
+```
+
+**Auto-detected method** (fastest available):
+
+1. **CoW** (APFS clonefile / Linux reflink) — fastest, instant
+2. **Git worktree** — for git projects on non-CoW filesystems
+3. **Full copy** — universal fallback
+
+---
+
+## Installation
+
+```bash
+pi install https://github.com/monotykamary/pi-var
+```
+
+Or project-local:
+
+```bash
+pi install -l https://github.com/monotykamary/pi-var
+```
+
+---
+
+## Usage
+
+### Natural Language
+
+Just describe what you need:
+
+> "Work on the new dashboard feature while I fix this bug in main"
+
+The AI automatically:
+
+1. Creates a variation for the dashboard work
+2. Redirects all operations to that variation
+3. When you mention the bug fix, creates another variation
+4. Switches between them transparently
+5. Merges completed work back
+
+### Dev Server Isolation
+
+> "Run this experiment on a different port so my main dev server keeps running"
+
+The AI:
+
+1. Creates a variation
+2. Allocates a unique port via `npx portless`
+3. Runs the dev server
+4. All without touching your main server
+
+---
+
+## For Users: Manual Commands
+
+If you need to intervene or check status:
+
+| Command                | Purpose                             |
+| ---------------------- | ----------------------------------- |
+| `/var`                 | Show status and active variation    |
+| `/var list`            | List all variations                 |
+| `/var clean <name>`    | Delete a variation                  |
+| `/var clean --stale 7` | Delete variations older than 7 days |
+| `/var stop`            | Return to source directory          |
+
+---
+
+## For the AI: Tools Reference
+
+### create_variation
+
+Create an isolated workspace automatically.
+
+```typescript
+{
+  purpose: string;           // "fix auth redirect bug"
+  type?: 'cow' | 'worktree' | 'copy';  // Auto-detected if omitted
+  createBranch?: boolean;    // Create git branch for worktrees
+}
+```
+
+**Auto-generated name:** Creates semantic names from `purpose` (e.g., `fix-auth-redirect-bug`).
+
+**Port isolation:** For dev servers, use `npx portless` via bash:
+
+```bash
+export PORT=$(npx portless --json | jq -r '.port')
+npm run dev
+```
+
+### merge_variation
+
+Merge current variation back to source.
+
+```typescript
+{
+  dryRun?: boolean;   // Preview changes
+}
+```
+
+**Variations persist after merge.** They are never automatically deleted to protect against data loss. Use `/var clean` to remove old variations.
+
+---
+
+## Environment Synchronization
+
+**Copied files:** `.env`, `.envrc`, `.npmrc`, `.tool-versions`, `.node-version`
+
+**Symlinked directories:** `node_modules`, `.next`, `.nuxt`, `target/`, `.venv/`
+
+This saves gigabytes of disk space while ensuring each variation has isolated environment configuration.
+
+---
+
+## Transparent Redirection
+
+When a variation is active:
+
+- `read` → reads from variation directory
+- `edit` → modifies files in variation
+- `write` → creates files in variation
+- `bash` → executes in variation directory
+- External paths (outside project) → accessed directly
+
+The footer shows: `🌿 variation-name`
+
+---
+
+## Comparison
+
+### vs Git Worktrees Alone
+
+| Feature          | Git Worktrees       | pi-var                     |
+| ---------------- | ------------------- | -------------------------- |
+| Setup            | Manual branching    | Automatic                  |
+| File redirection | Manual `cd`         | Transparent                |
+| Environment sync | Manual copy/symlink | Automatic                  |
+| Port conflicts   | Manual management   | AI handles via portless    |
+| Best method      | Git only            | CoW > worktree > copy      |
+| Cleanup          | Manual git commands | AI-managed or `/var clean` |
+
+### vs Docker/Dev Containers
+
+- **pi-var:** Native filesystem performance, instant startup, same environment
+- **Docker:** True OS isolation, image builds, slower startup
+
+Use pi-var for parallel development work. Use Docker for different OS/toolchain environments.
+
+---
+
+## Configuration
+
+Create `.varconfig.yaml` in project root for custom sync rules:
+
+```yaml
+# Files to copy
+copy:
+  - .env.local
+  - secrets.json
+
+# Directories to symlink
+symlink:
+  - node_modules
+  - .turbo
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT

package/commitlint.config.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};

package/extensions/pi-var/__tests__/integration/smoke.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Integration/smoke tests for pi-var extension
+ *
+ * These tests verify the end-to-end functionality of the /var command
+ * in a real (but isolated) environment.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest';
+import { mkdir, rm, writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+describe('pi-var smoke tests', () => {
+  const testDir = join(tmpdir(), `pi-var-test-${Date.now()}`);
+  let originalCwd: string;
+
+  beforeAll(async () => {
+    originalCwd = process.cwd();
+
+    // Create test project structure
+    await mkdir(testDir, { recursive: true });
+    await mkdir(join(testDir, 'src'), { recursive: true });
+
+    // Create a simple package.json
+    await writeFile(
+      join(testDir, 'package.json'),
+      JSON.stringify({
+        name: 'test-project',
+        version: '1.0.0',
+      })
+    );
+
+    // Create a source file
+    await writeFile(join(testDir, 'src', 'index.js'), 'console.log("Hello from main");');
+
+    // Initialize git repo for worktree tests
+    try {
+      execSync('git init', { cwd: testDir, stdio: 'ignore' });
+      execSync('git config user.email "test@test.com"', { cwd: testDir, stdio: 'ignore' });
+      execSync('git config user.name "Test User"', { cwd: testDir, stdio: 'ignore' });
+      execSync('git add .', { cwd: testDir, stdio: 'ignore' });
+      execSync('git commit -m "Initial commit"', { cwd: testDir, stdio: 'ignore' });
+    } catch {
+      // Git may not be available, skip git-related tests
+    }
+
+    process.chdir(testDir);
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('Extension loading', () => {
+    it('should have required files', async () => {
+      // Verify extension structure exists - use a path that works from test directory
+      const fs = await import('node:fs');
+      const { dirname } = await import('node:path');
+      const { fileURLToPath } = await import('node:url');
+
+      // Get the extension root from the current test file location
+      const testDir = dirname(fileURLToPath(import.meta.url));
+      const extensionPath = dirname(dirname(testDir)); // Up two levels from __tests__/integration
+
+      expect(fs.existsSync(join(extensionPath, 'index.ts'))).toBe(true);
+      expect(fs.existsSync(join(extensionPath, 'src', 'types', 'index.ts'))).toBe(true);
+      expect(fs.existsSync(join(extensionPath, 'src', 'tools', 'command', 'index.ts'))).toBe(true);
+      expect(fs.existsSync(join(extensionPath, 'src', 'state', 'store.ts'))).toBe(true);
+    });
+  });
+
+  describe('Type definitions', () => {
+    it('should be importable', async () => {
+      const types = await import('../../src/types/index.js');
+      // TypeScript types don't exist at runtime, just verify module loads
+      expect(types).toBeDefined();
+    });
+  });
+
+  describe('State management', () => {
+    it('should create runtime store', async () => {
+      const { createRuntimeStore, getSessionKey } = await import('../../src/state/index.js');
+
+      const store = createRuntimeStore();
+      expect(store).toHaveProperty('ensure');
+      expect(store).toHaveProperty('get');
+      expect(store).toHaveProperty('delete');
+
+      const mockContext = {
+        sessionManager: {
+          getSessionId: () => 'test-session-123',
+        },
+      };
+
+      const key = getSessionKey(mockContext as any);
+      expect(key).toBe('test-session-123');
+    });
+
+    it('should manage runtime lifecycle', async () => {
+      const { createRuntimeStore } = await import('../../src/state/store.js');
+
+      const store = createRuntimeStore();
+
+      // Create runtime
+      const runtime = store.ensure('session-1');
+      expect(runtime.state.sessionId).toBe('session-1');
+      expect(runtime.state.activeVariationId).toBeNull();
+      expect(runtime.state.variations).toEqual([]);
+
+      // Modify and verify persistence
+      runtime.state.activeVariationId = 'test-variation';
+
+      const retrieved = store.get('session-1');
+      expect(retrieved?.state.activeVariationId).toBe('test-variation');
+
+      // Delete
+      const deleted = store.delete('session-1');
+      expect(deleted).toBe(true);
+      expect(store.get('session-1')).toBeUndefined();
+    });
+  });
+
+  describe('Name generation', () => {
+    it('should generate unique IDs', async () => {
+      const { generateVariationId } = await import('../../src/utils/names.js');
+
+      const id1 = generateVariationId();
+      const id2 = generateVariationId();
+
+      expect(id1).toBeDefined();
+      expect(id2).toBeDefined();
+      expect(id1).not.toBe(id2);
+      expect(id1.length).toBeGreaterThan(10);
+    });
+
+    it('should generate readable names', async () => {
+      const { generateVariationName } = await import('../../src/utils/names.js');
+
+      const name = generateVariationName();
+
+      expect(name).toBeDefined();
+      expect(name).toMatch(/^[a-z]+-[a-z]+$/);
+      expect(name.length).toBeGreaterThan(3);
+    });
+
+    it('should generate different names on multiple calls', async () => {
+      const { generateVariationName } = await import('../../src/utils/names.js');
+
+      const names = new Set();
+      for (let i = 0; i < 10; i++) {
+        names.add(generateVariationName());
+      }
+
+      // With 30 adjectives and 38 nouns, we should get variety
+      expect(names.size).toBeGreaterThan(5);
+    });
+  });
+
+  describe('Command registration', () => {
+    it('should export registerVarCommand', async () => {
+      const command = await import('../../src/tools/command/index.js');
+
+      expect(command).toHaveProperty('registerVarCommand');
+      expect(typeof command.registerVarCommand).toBe('function');
+    });
+
+    it('should accept ExtensionAPI and dependencies', async () => {
+      const { registerVarCommand } = await import('../../src/tools/command/index.js');
+
+      const mockPi = {
+        registerCommand: () => {},
+        on: () => {},
+        appendEntry: () => {},
+      };
+
+      const mockRuntime = {
+        state: { activeVariationId: null, variations: [], sessionId: 'test' },
+
+        lastPersisted: Date.now(),
+      };
+
+      const mockRuntimeStore = {
+        ensure: () => mockRuntime,
+        get: () => mockRuntime,
+        delete: () => true,
+        persistState: () => {},
+        restoreState: () => {},
+      };
+
+      // Should not throw
+      expect(() => {
+        registerVarCommand(mockPi as any, {
+          getRuntime: () => mockRuntime,
+          pi: mockPi as any,
+          runtimeStore: mockRuntimeStore as any,
+        });
+      }).not.toThrow();
+    });
+  });
+
+  describe('Extension integration', () => {
+    it('should have complete extension structure', async () => {
+      const extension = await import('../../index.js');
+
+      expect(extension).toHaveProperty('default');
+      expect(typeof extension.default).toBe('function');
+    });
+
+    it('should initialize with ExtensionAPI', async () => {
+      const extension = await import('../../index.js');
+
+      const calls: string[] = [];
+      const mockPi = {
+        registerCommand: (name: string) => calls.push(`registerCommand:${name}`),
+        registerTool: (tool: any) => calls.push(`registerTool:${tool.name || 'unnamed'}`),
+        on: (event: string) => calls.push(`on:${event}`),
+        exec: () => Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+      };
+
+      // Should not throw when initializing
+      expect(() => {
+        extension.default(mockPi as any);
+      }).not.toThrow();
+
+      // Should have registered the /var command
+      expect(calls.some((c) => c.includes('var'))).toBe(true);
+    });
+  });
+
+  describe('File operations integration', () => {
+    it('should create and read files in test directory', async () => {
+      const testFile = join(testDir, 'test-file.txt');
+      const content = 'Hello from test';
+
+      await writeFile(testFile, content);
+      const read = await readFile(testFile, 'utf-8');
+
+      expect(read).toBe(content);
+    });
+
+    it('should handle directory creation', async () => {
+      const nestedDir = join(testDir, 'nested', 'deep', 'dir');
+
+      await mkdir(nestedDir, { recursive: true });
+
+      const fs = await import('node:fs');
+      expect(fs.existsSync(nestedDir)).toBe(true);
+    });
+  });
+
+  describe('Portless integration (mocked)', () => {
+    it('should handle missing portless gracefully', async () => {
+      const { registerVarCommand } = await import('../../src/tools/command/index.js');
+
+      const mockRuntime = {
+        state: { activeVariationId: null, variations: [], sessionId: 'test' },
+
+        lastPersisted: Date.now(),
+      };
+
+      let handler: Function | undefined;
+      const mockPi = {
+        registerCommand: (name: string, config: any) => {
+          handler = config.handler;
+        },
+        on: () => {},
+        appendEntry: () => {},
+      };
+
+      const notifications: Array<{ msg: string; type: string }> = [];
+      const mockCtx = {
+        cwd: testDir,
+        ui: {
+          notify: (msg: string, type: string) => notifications.push({ msg, type }),
+          setStatus: () => {},
+          confirm: () => Promise.resolve(true),
+          select: () => Promise.resolve(null),
+        },
+        sessionManager: { getSessionId: () => 'test', getSessionFile: () => '' },
+      };
+
+      registerVarCommand(mockPi as any, {
+        getRuntime: () => mockRuntime,
+        pi: mockPi as any,
+        runtimeStore: {
+          ensure: () => mockRuntime,
+          get: () => mockRuntime,
+          delete: () => true,
+          persistState: () => {},
+          restoreState: () => {},
+        } as any,
+      });
+
+      // Attempt to create variation with --isolated (portless won't be available)
+      // Should handle gracefully and not crash
+      try {
+        await handler?.('new test-isolated --isolated', mockCtx as any);
+      } catch {
+        // Expected to potentially fail without real portless
+      }
+
+      // Extension should still be functional
+      expect(mockRuntime.state.variations.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+});