pi-var 1.0.1

package/extensions/pi-var/src/environment/detect.ts

@@ -0,0 +1,91 @@
+/**
+ * Variation context detection from current working directory
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+import type { VariationContext } from '../types/index';
+
+/**
+ * Detect variation context from current working directory
+ * Returns information about whether we're in a variation and which one
+ */
+export function detectVariationContext(cwd: string): VariationContext {
+  // Normalize path
+  const normalizedCwd = path.resolve(cwd);
+
+  // Check if we're inside a .pi/variations directory structure
+  const variationsPattern = /[\/\\]\.pi[\/\\]variations[\/\\][^\/\\]+[\/\\]([^\/\\]+)[\/\\]?/;
+  const match = normalizedCwd.match(variationsPattern);
+
+  if (match) {
+    const variationName = match[1];
+    const variationPath = normalizedCwd.substring(
+      0,
+      normalizedCwd.indexOf(match[0]) + match[0].length
+    );
+
+    // Find source path (go up to project root)
+    const sourcePath = path.dirname(path.dirname(path.dirname(path.dirname(variationPath))));
+
+    // Generate a consistent variation ID based on path
+    const variationId = `var-${Buffer.from(variationPath)
+      .toString('base64')
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .slice(0, 16)}`;
+
+    return {
+      inVariation: true,
+      variationId,
+      variationName,
+      variationPath,
+      sourcePath,
+    };
+  }
+
+  // Not in a variation - return context with cwd as source
+  return {
+    inVariation: false,
+    variationId: null,
+    variationName: null,
+    variationPath: null,
+    sourcePath: normalizedCwd,
+  };
+}
+
+/**
+ * Detect variation context async - checks for marker file
+ * Use this when you need to detect via marker file
+ */
+export async function detectVariationContextAsync(cwd: string): Promise<VariationContext> {
+  // First try the sync version
+  const syncContext = detectVariationContext(cwd);
+  if (syncContext.inVariation) {
+    return syncContext;
+  }
+
+  // Check for .pi-variation marker file
+  const normalizedCwd = path.resolve(cwd);
+  const markerPath = path.join(normalizedCwd, '.pi-variation');
+
+  try {
+    const stat = await fs.stat(markerPath);
+    if (stat.isFile()) {
+      const content = await fs.readFile(markerPath, 'utf-8');
+      const info = JSON.parse(content);
+      if (info.sourcePath && info.variationName) {
+        return {
+          inVariation: true,
+          variationId: info.id || 'var-unknown',
+          variationName: info.variationName,
+          variationPath: normalizedCwd,
+          sourcePath: info.sourcePath,
+        };
+      }
+    }
+  } catch {
+    // No marker file or error reading it, ignore
+  }
+
+  return syncContext;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Environment setup and variation context detection module
+ */
+
+import type { VarConfig } from '../types/index';
+import { copyEnvFiles } from './copy-env';
+import { symlinkHeavyDirs } from './symlink';
+import { detectVariationContext, detectVariationContextAsync } from './detect';
+import { createVariationMarker, removeVariationMarker } from './marker';
+
+// Default configuration for environment sync
+export const DEFAULT_CONFIG = {
+  copy: ['.env', '.env.*', '.envrc', '.npmrc', '.tool-versions'],
+  symlink: ['node_modules', '.next', '.nuxt', 'target', '.venv'],
+  postCreate: [],
+};
+
+/**
+ * Setup the variation environment by copying env files and symlinking heavy directories
+ */
+export async function setupVariationEnvironment(
+  source: string,
+  variation: string,
+  config: Partial<VarConfig> = {}
+): Promise<void> {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+
+  // Copy environment files
+  await copyEnvFiles(source, variation, mergedConfig.copy);
+
+  // Symlink heavy directories
+  await symlinkHeavyDirs(source, variation, mergedConfig.symlink);
+
+  // Run post-create commands
+  for (const cmd of mergedConfig.postCreate) {
+    try {
+      const { exec } = await import('child_process');
+      const { promisify } = await import('util');
+      const execAsync = promisify(exec);
+      await execAsync(cmd, { cwd: variation });
+    } catch (err) {
+      console.warn(`Post-create command failed: ${cmd}`, err);
+    }
+  }
+}
+
+export {
+  detectVariationContext,
+  detectVariationContextAsync,
+  createVariationMarker,
+  removeVariationMarker,
+  copyEnvFiles,
+  symlinkHeavyDirs,
+};

package/extensions/pi-var/src/environment/marker.ts

@@ -0,0 +1,42 @@
+/**
+ * Variation marker file management
+ */
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+/**
+ * Create a marker file in the variation for context detection
+ */
+export async function createVariationMarker(
+  variationPath: string,
+  info: {
+    id: string;
+    name: string;
+    sourcePath: string;
+    type: string;
+  }
+): Promise<void> {
+  const markerPath = path.join(variationPath, '.pi-variation');
+  const content = {
+    id: info.id,
+    variationName: info.name,
+    sourcePath: info.sourcePath,
+    type: info.type,
+    createdAt: new Date().toISOString(),
+  };
+
+  await fs.writeFile(markerPath, JSON.stringify(content, null, 2));
+}
+
+/**
+ * Remove the variation marker file
+ */
+export async function removeVariationMarker(variationPath: string): Promise<void> {
+  const markerPath = path.join(variationPath, '.pi-variation');
+  try {
+    await fs.unlink(markerPath);
+  } catch {
+    // Ignore if doesn't exist
+  }
+}

package/extensions/pi-var/src/environment/symlink.ts

@@ -0,0 +1,82 @@
+/**
+ * Symlink management for heavy directories
+ */
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+/**
+ * Create symlinks for heavy directories (node_modules, .next, etc.)
+ */
+export async function symlinkHeavyDirs(
+  source: string,
+  variation: string,
+  dirNames: string[]
+): Promise<void> {
+  for (const dirName of dirNames) {
+    const srcPath = path.join(source, dirName);
+    const destPath = path.join(variation, dirName);
+
+    try {
+      // Check if source directory exists
+      const stat = await fs.stat(srcPath);
+      if (!stat.isDirectory()) {
+        continue;
+      }
+
+      // Ensure the variation parent directory exists
+      await fs.mkdir(path.dirname(destPath), { recursive: true });
+
+      // Remove destination if it exists (but is not a symlink)
+      try {
+        const destStat = await fs.lstat(destPath);
+        if (destStat.isSymbolicLink()) {
+          // Already a symlink, might be from previous setup
+          await fs.unlink(destPath);
+        } else if (destStat.isDirectory()) {
+          // It's a directory - remove it to replace with symlink
+          await fs.rm(destPath, { recursive: true });
+        } else {
+          // It's a file
+          await fs.unlink(destPath);
+        }
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw err;
+        }
+        // Destination doesn't exist, proceed
+      }
+
+      // Create the symlink
+      // Use relative path for portability
+      const relativeSrc = path.relative(path.dirname(destPath), srcPath);
+      await fs.symlink(relativeSrc, destPath, 'junction');
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        // Source directory doesn't exist, skip
+        continue;
+      }
+      // Log but don't throw - symlinks are optional optimizations
+      console.warn(`Failed to symlink ${dirName}:`, (err as Error).message);
+    }
+  }
+}
+
+/**
+ * Remove symlinks from a variation (before merge or delete)
+ * @internal Not currently used but kept for future cleanup operations
+ */
+async function removeSymlinks(variation: string): Promise<void> {
+  try {
+    const entries = await fs.readdir(variation, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        const linkPath = path.join(variation, entry.name);
+        await fs.unlink(linkPath);
+      }
+    }
+  } catch (err) {
+    // Ignore errors during cleanup
+  }
+}

package/extensions/pi-var/src/gitignore/manager.ts

@@ -0,0 +1,77 @@
+/**
+ * Global gitignore management for .pi/variations
+ */
+
+import { promises as fs, constants as fsConstants } from 'fs';
+import * as fsSync from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+/** Get the path to the global gitignore file */
+function getGlobalGitignorePath(): string | null {
+  try {
+    // Check if core.excludesfile is set
+    const result = execSync('git config --global core.excludesfile', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    const configured = result.trim();
+    if (configured) return configured;
+  } catch {
+    // Not configured, fall through to default
+  }
+
+  // Default locations by platform
+  // Check env vars first (allows testing with fake home), then os.homedir()
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const candidates = [
+    path.join(home, '.gitignore'),
+    path.join(home, '.gitignore_global'),
+    path.join(home, '.config', 'git', 'ignore'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fsSync.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Default to ~/.gitignore if nothing exists
+  return path.join(home, '.gitignore');
+}
+
+/** Ensure .pi/variations/ is in the global gitignore */
+export function ensureGlobalGitignore(): void {
+  try {
+    const gitignorePath = getGlobalGitignorePath();
+    if (!gitignorePath) return;
+
+    const pattern = '.pi/variations/';
+    let content = '';
+
+    if (fsSync.existsSync(gitignorePath)) {
+      content = fsSync.readFileSync(gitignorePath, 'utf-8');
+      // Already present?
+      if (content.split(/\r?\n/).some((line) => line.trim() === pattern)) {
+        return;
+      }
+    }
+
+    // Ensure parent directory exists
+    const parentDir = path.dirname(gitignorePath);
+    if (!fsSync.existsSync(parentDir)) {
+      fsSync.mkdirSync(parentDir, { recursive: true });
+    }
+
+    // Append with a comment
+    const entry =
+      content.endsWith('\n') || content === ''
+        ? `# pi-var variations\n${pattern}\n`
+        : `\n# pi-var variations\n${pattern}\n`;
+
+    fsSync.appendFileSync(gitignorePath, entry, 'utf-8');
+  } catch {
+    // Silently fail — this is a convenience, not a requirement
+  }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * State management module
+ */
+
+export type { ExtensionContext, SessionManager } from './types';
+export { getSessionKey } from './keys';
+export { createRuntimeStore } from './store.js';

package/extensions/pi-var/src/state/keys.ts

@@ -0,0 +1,14 @@
+/**
+ * Session key extraction
+ */
+
+import type { ExtensionContext } from './types';
+
+/**
+ * Extract session ID from extension context
+ * @param ctx - Extension context containing session manager
+ * @returns Session key string
+ */
+export function getSessionKey(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId?.() || 'default';
+}

package/extensions/pi-var/src/state/store.ts

@@ -0,0 +1,110 @@
+/**
+ * State persistence and restoration
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { VAR_STATE_ENTRY_TYPE, PersistedVarState, SessionManager, RuntimeStore } from './types.js';
+import type { VarRuntime, VarState } from '../types/index.js';
+
+/**
+ * Create default initial state for a new session
+ * @param sessionId - The session identifier
+ * @returns Initial VarState object
+ */
+function createInitialState(sessionId: string): VarState {
+  return {
+    activeVariationId: null,
+    variations: [],
+    sessionId,
+  };
+}
+
+/**
+ * Create a new VarRuntime instance with initial state
+ * @param sessionId - The session identifier
+ * @returns New VarRuntime instance
+ */
+function createRuntime(sessionId: string): VarRuntime {
+  return {
+    state: createInitialState(sessionId),
+    lastPersisted: Date.now(),
+  };
+}
+
+/**
+ * Create Map-based runtime store for managing per-session VarRuntime instances
+ * @returns RuntimeStore instance with ensure, get, delete, and persistState methods
+ */
+export function createRuntimeStore(): RuntimeStore {
+  const store = new Map<string, VarRuntime>();
+
+  return {
+    ensure(sessionKey: string): VarRuntime {
+      let runtime = store.get(sessionKey);
+      if (!runtime) {
+        runtime = createRuntime(sessionKey);
+        store.set(sessionKey, runtime);
+      }
+      return runtime;
+    },
+
+    get(sessionKey: string): VarRuntime | undefined {
+      return store.get(sessionKey);
+    },
+
+    delete(sessionKey: string): boolean {
+      return store.delete(sessionKey);
+    },
+
+    persistState(sessionKey: string, pi: ExtensionAPI): void {
+      const runtime = store.get(sessionKey);
+      if (!runtime) return;
+
+      const persistedState: PersistedVarState = {
+        variations: runtime.state.variations,
+        activeVariationId: runtime.state.activeVariationId,
+      };
+
+      pi.appendEntry(VAR_STATE_ENTRY_TYPE, persistedState);
+      runtime.lastPersisted = Date.now();
+    },
+
+    restoreState(sessionKey: string, sessionManager: SessionManager): void {
+      const runtime = store.get(sessionKey);
+      if (!runtime) return;
+
+      // Get entries - prefer getEntries() as it's always available during session_start
+      // getBranch() may fail early in session lifecycle before tree is initialized
+      let entries: SessionEntry[] = [];
+      try {
+        if (sessionManager.getEntries) {
+          entries = sessionManager.getEntries();
+        } else if (sessionManager.getBranch) {
+          entries = sessionManager.getBranch();
+        }
+      } catch {
+        // Session manager may not be fully initialized yet
+        return;
+      }
+
+      if (!entries || entries.length === 0) return;
+
+      // Find the last state entry (entries are in order, so we take the last one)
+      const stateEntries = entries.filter(
+        (e: SessionEntry) => e.type === 'custom' && e.customType === VAR_STATE_ENTRY_TYPE
+      );
+
+      if (stateEntries.length === 0) return;
+
+      const lastEntry = stateEntries[stateEntries.length - 1];
+      const persistedState = lastEntry.data as PersistedVarState;
+
+      if (persistedState) {
+        runtime.state.variations = persistedState.variations || [];
+        runtime.state.activeVariationId = persistedState.activeVariationId ?? null;
+      }
+    },
+  };
+}
+
+import type { SessionEntry } from './types.js';

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

@@ -0,0 +1,70 @@
+/**
+ * State types and interfaces
+ */
+
+import type { VarRuntime, VarState, Variation } from '../types/index';
+
+/** Custom entry type for session persistence */
+export const VAR_STATE_ENTRY_TYPE = 'pi-var:state';
+
+/** Serialized state for persistence */
+export interface PersistedVarState {
+  variations: Variation[];
+  activeVariationId: string | null;
+}
+
+/** Session entry interface for state restoration */
+export interface SessionEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/** Session manager interface for accessing entries */
+export interface SessionManager {
+  getEntries?(): SessionEntry[];
+  getBranch?(): SessionEntry[];
+  getSessionId?(): string;
+}
+
+/**
+ * Extension context interface for session key extraction
+ */
+export interface ExtensionContext {
+  sessionManager: SessionManager;
+}
+
+/**
+ * Runtime store interface for managing per-session VarRuntime instances
+ * @internal
+ */
+export interface RuntimeStore {
+  /**
+   * Ensure a VarRuntime exists for the given session key,
+   * creating one if it doesn't exist
+   */
+  ensure(sessionKey: string): VarRuntime;
+
+  /**
+   * Get an existing VarRuntime for the session key,
+   * returning undefined if not found
+   */
+  get(sessionKey: string): VarRuntime | undefined;
+
+  /**
+   * Delete a VarRuntime for the given session key
+   */
+  delete(sessionKey: string): boolean;
+
+  /**
+   * Persist current state to the session using pi.appendEntry()
+   */
+  persistState(sessionKey: string, pi: ExtensionAPI): void;
+
+  /**
+   * Restore state from session entries
+   */
+  restoreState(sessionKey: string, sessionManager: SessionManager): void;
+}
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

package/extensions/pi-var/src/tools/command/clean.ts

@@ -0,0 +1,87 @@
+/**
+ * /var command clean handlers
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import { removeVariation } from '../../variation/remove';
+import type { RuntimeStore } from '../../state/types';
+
+function getSessionKey(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId?.() || 'default';
+}
+
+export async function handleCleanStale(
+  runtime: VarRuntime,
+  ctx: ExtensionContext,
+  staleDays: number,
+  runtimeStore: RuntimeStore,
+  pi: ExtensionAPI
+): Promise<void> {
+  const cutoff = Date.now() - staleDays * 24 * 60 * 60 * 1000;
+
+  const staleVariations = runtime.state.variations.filter((v) => {
+    const lastAccessed = new Date(v.lastAccessed).getTime();
+    return lastAccessed < cutoff;
+  });
+
+  if (staleVariations.length === 0) {
+    ctx.ui.notify(`No variations older than ${staleDays} days`, 'info');
+    return;
+  }
+
+  const confirmed = await ctx.ui.confirm(
+    'Clean stale variations?',
+    `Delete ${staleVariations.length} variation(s) older than ${staleDays} days?`
+  );
+
+  if (!confirmed) return;
+
+  for (const v of staleVariations) {
+    await removeVariation(v);
+    runtime.state.variations = runtime.state.variations.filter((existing) => existing.id !== v.id);
+  }
+
+  // Persist state after cleaning
+  runtimeStore.persistState(getSessionKey(ctx), pi);
+
+  ctx.ui.notify(`Cleaned ${staleVariations.length} stale variation(s)`, 'info');
+}
+
+export async function handleCleanSpecific(
+  runtime: VarRuntime,
+  ctx: ExtensionContext,
+  name: string,
+  runtimeStore: RuntimeStore,
+  pi: ExtensionAPI
+): Promise<void> {
+  const variation = runtime.state.variations.find((v) => v.name === name);
+  if (!variation) {
+    ctx.ui.notify(`Variation "${name}" not found`, 'error');
+    return;
+  }
+
+  const confirmed = await ctx.ui.confirm(
+    'Delete variation?',
+    `Delete "${name}"? This cannot be undone.`
+  );
+
+  if (!confirmed) {
+    ctx.ui.notify('Clean cancelled', 'info');
+    return;
+  }
+
+  await removeVariation(variation);
+  runtime.state.variations = runtime.state.variations.filter((v) => v.id !== variation.id);
+
+  // If this was active, deactivate
+  if (runtime.state.activeVariationId === variation.id) {
+    runtime.state.activeVariationId = null;
+    ctx.ui.setStatus('pi-var', '');
+  }
+
+  // Persist state after cleaning
+  runtimeStore.persistState(getSessionKey(ctx), pi);
+
+  ctx.ui.notify(`Deleted variation "${name}"`, 'info');
+}