cluttry 1.0.0

package/src/lib/output.ts

@@ -0,0 +1,102 @@
+/**
+ * Output utilities for VWT
+ *
+ * Provides consistent, colorful terminal output without external dependencies.
+ */
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+};
+
+// Check if colors should be used
+const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function colorize(text: string, ...codes: string[]): string {
+  if (!useColors) return text;
+  return codes.join('') + text + colors.reset;
+}
+
+export const fmt = {
+  bold: (text: string) => colorize(text, colors.bold),
+  dim: (text: string) => colorize(text, colors.dim),
+  red: (text: string) => colorize(text, colors.red),
+  green: (text: string) => colorize(text, colors.green),
+  yellow: (text: string) => colorize(text, colors.yellow),
+  blue: (text: string) => colorize(text, colors.blue),
+  magenta: (text: string) => colorize(text, colors.magenta),
+  cyan: (text: string) => colorize(text, colors.cyan),
+  gray: (text: string) => colorize(text, colors.gray),
+
+  success: (text: string) => colorize(text, colors.green),
+  error: (text: string) => colorize(text, colors.red),
+  warn: (text: string) => colorize(text, colors.yellow),
+  info: (text: string) => colorize(text, colors.cyan),
+  path: (text: string) => colorize(text, colors.blue),
+  branch: (text: string) => colorize(text, colors.magenta),
+};
+
+export function log(message: string): void {
+  console.log(message);
+}
+
+export function success(message: string): void {
+  console.log(fmt.green('✓') + ' ' + message);
+}
+
+export function error(message: string): void {
+  console.error(fmt.red('✗') + ' ' + message);
+}
+
+export function warn(message: string): void {
+  console.log(fmt.yellow('⚠') + ' ' + message);
+}
+
+export function info(message: string): void {
+  console.log(fmt.cyan('ℹ') + ' ' + message);
+}
+
+export function header(message: string): void {
+  console.log('\n' + fmt.bold(message));
+}
+
+export function list(items: string[], prefix = '  '): void {
+  for (const item of items) {
+    console.log(prefix + '• ' + item);
+  }
+}
+
+export function table(rows: string[][], columnWidths?: number[]): void {
+  if (rows.length === 0) return;
+
+  // Calculate column widths if not provided
+  const widths = columnWidths ?? rows[0].map((_, i) =>
+    Math.max(...rows.map(row => (row[i] ?? '').length))
+  );
+
+  for (const row of rows) {
+    const paddedCells = row.map((cell, i) =>
+      (cell ?? '').padEnd(widths[i] ?? 0)
+    );
+    console.log('  ' + paddedCells.join('  '));
+  }
+}
+
+export function json(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function newline(): void {
+  console.log();
+}

package/src/lib/paths.ts

@@ -0,0 +1,108 @@
+/**
+ * Path utilities for VWT
+ */
+
+import path from 'node:path';
+
+/**
+ * Sanitize a branch name for use in filesystem paths
+ * - Replace slashes with double dashes
+ * - Remove or replace other problematic characters
+ */
+export function sanitizeBranchName(branch: string): string {
+  return branch
+    .replace(/\//g, '--')  // Replace slashes with double dashes
+    .replace(/[<>:"|?*\\]/g, '-')  // Replace Windows-forbidden chars
+    .replace(/\s+/g, '-')  // Replace whitespace
+    .replace(/^\.+/, '')  // Remove leading dots
+    .replace(/\.+$/, '')  // Remove trailing dots
+    .replace(/-+/g, '-')  // Collapse multiple dashes
+    .replace(/^-+/, '')  // Remove leading dashes
+    .replace(/-+$/, '');  // Remove trailing dashes
+}
+
+/**
+ * Calculate the default worktree path
+ */
+export function getDefaultWorktreePath(
+  repoRoot: string,
+  branch: string,
+  options?: {
+    explicitPath?: string;
+    baseDir?: string;
+    repoName?: string;
+  }
+): string {
+  // Explicit path wins
+  if (options?.explicitPath) {
+    // If it's relative, resolve against CWD
+    if (!path.isAbsolute(options.explicitPath)) {
+      return path.resolve(options.explicitPath);
+    }
+    return options.explicitPath;
+  }
+
+  const sanitizedBranch = sanitizeBranchName(branch);
+
+  // Base directory specified
+  if (options?.baseDir) {
+    const repoName = options.repoName ?? path.basename(repoRoot);
+    const baseDir = path.isAbsolute(options.baseDir)
+      ? options.baseDir
+      : path.resolve(repoRoot, options.baseDir);
+    return path.join(baseDir, repoName, sanitizedBranch);
+  }
+
+  // Default: .worktrees/<branch> inside repo
+  return path.join(repoRoot, '.worktrees', sanitizedBranch);
+}
+
+/**
+ * Check if a path is inside the .worktrees directory
+ */
+export function isInsideWorktreesDir(targetPath: string, repoRoot: string): boolean {
+  const worktreesDir = path.join(repoRoot, '.worktrees');
+  const normalizedTarget = path.normalize(targetPath);
+  const normalizedWorktrees = path.normalize(worktreesDir);
+  return normalizedTarget.startsWith(normalizedWorktrees);
+}
+
+/**
+ * Get relative path from repo root
+ */
+export function getRelativePath(absolutePath: string, repoRoot: string): string {
+  return path.relative(repoRoot, absolutePath);
+}
+
+/**
+ * Resolve a branch-or-path argument to a worktree path
+ */
+export function resolveBranchOrPath(
+  branchOrPath: string,
+  worktrees: Array<{ branch: string | null; path: string }>,
+  repoRoot: string
+): { path: string; branch: string | null } | null {
+  // First, try to match by branch name
+  const byBranch = worktrees.find((w) => w.branch === branchOrPath);
+  if (byBranch) {
+    return { path: byBranch.path, branch: byBranch.branch };
+  }
+
+  // Try to match by path (absolute or relative)
+  const absolutePath = path.isAbsolute(branchOrPath)
+    ? branchOrPath
+    : path.resolve(repoRoot, branchOrPath);
+
+  const byPath = worktrees.find((w) => path.normalize(w.path) === path.normalize(absolutePath));
+  if (byPath) {
+    return { path: byPath.path, branch: byPath.branch };
+  }
+
+  // Try partial path match (end of path)
+  const byPartialPath = worktrees.find((w) => w.path.endsWith(branchOrPath));
+  if (byPartialPath) {
+    return { path: byPartialPath.path, branch: byPartialPath.branch };
+  }
+
+  return null;
+}

package/src/lib/secrets.ts

@@ -0,0 +1,193 @@
+/**
+ * Secret file handling for VWT
+ *
+ * This module ensures that only git-ignored files are ever copied or symlinked.
+ * It provides a safety layer to prevent accidentally exposing tracked files.
+ */
+
+import { existsSync, copyFileSync, symlinkSync, mkdirSync, statSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { glob } from 'glob';
+import { isTracked, isIgnored } from './git.js';
+import type { SecretMode } from './types.js';
+
+export interface FileCheckResult {
+  path: string;
+  exists: boolean;
+  isTracked: boolean;
+  isIgnored: boolean;
+  safe: boolean;
+  reason?: string;
+}
+
+/**
+ * Check if a file is safe to copy/symlink
+ * A file is safe if:
+ * 1. It exists
+ * 2. It is NOT tracked by git
+ * 3. It IS ignored by git
+ */
+export function checkFileSafety(filePath: string, repoRoot: string): FileCheckResult {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(repoRoot, filePath);
+  const relativePath = path.relative(repoRoot, absolutePath);
+
+  const result: FileCheckResult = {
+    path: relativePath,
+    exists: existsSync(absolutePath),
+    isTracked: false,
+    isIgnored: false,
+    safe: false,
+  };
+
+  if (!result.exists) {
+    result.reason = 'File does not exist';
+    return result;
+  }
+
+  result.isTracked = isTracked(relativePath, repoRoot);
+  if (result.isTracked) {
+    result.reason = 'File is tracked by git (would be committed)';
+    return result;
+  }
+
+  result.isIgnored = isIgnored(relativePath, repoRoot);
+  if (!result.isIgnored) {
+    result.reason = 'File is not ignored by git (could be accidentally committed)';
+    return result;
+  }
+
+  result.safe = true;
+  return result;
+}
+
+/**
+ * Expand glob patterns to actual file paths
+ */
+export async function expandIncludePatterns(
+  patterns: string[],
+  repoRoot: string
+): Promise<string[]> {
+  const allFiles: Set<string> = new Set();
+
+  for (const pattern of patterns) {
+    try {
+      const matches = await glob(pattern, {
+        cwd: repoRoot,
+        dot: true,
+        nodir: true,
+      });
+      for (const match of matches) {
+        allFiles.add(match);
+      }
+    } catch {
+      // If glob fails, treat as literal path
+      if (existsSync(path.join(repoRoot, pattern))) {
+        allFiles.add(pattern);
+      }
+    }
+  }
+
+  return Array.from(allFiles).sort();
+}
+
+/**
+ * Get all safe files from include patterns
+ */
+export async function getSafeFiles(
+  patterns: string[],
+  repoRoot: string
+): Promise<{ safe: FileCheckResult[]; unsafe: FileCheckResult[] }> {
+  const files = await expandIncludePatterns(patterns, repoRoot);
+  const safe: FileCheckResult[] = [];
+  const unsafe: FileCheckResult[] = [];
+
+  for (const file of files) {
+    const result = checkFileSafety(file, repoRoot);
+    if (result.safe) {
+      safe.push(result);
+    } else if (result.exists) {
+      // Only report unsafe if file actually exists
+      unsafe.push(result);
+    }
+  }
+
+  return { safe, unsafe };
+}
+
+/**
+ * Copy a file to the target directory, preserving relative path
+ */
+export function copyFile(
+  relativePath: string,
+  sourceRoot: string,
+  targetRoot: string
+): void {
+  const sourcePath = path.join(sourceRoot, relativePath);
+  const targetPath = path.join(targetRoot, relativePath);
+
+  // Create parent directories if needed
+  const targetDir = path.dirname(targetPath);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  copyFileSync(sourcePath, targetPath);
+}
+
+/**
+ * Create a symlink in the target directory pointing to source
+ */
+export function createSymlink(
+  relativePath: string,
+  sourceRoot: string,
+  targetRoot: string
+): void {
+  const sourcePath = path.join(sourceRoot, relativePath);
+  const targetPath = path.join(targetRoot, relativePath);
+
+  // Create parent directories if needed
+  const targetDir = path.dirname(targetPath);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Use absolute path for symlink target for reliability
+  symlinkSync(sourcePath, targetPath);
+}
+
+/**
+ * Process files according to mode (copy or symlink)
+ */
+export async function processSecrets(
+  mode: SecretMode,
+  patterns: string[],
+  sourceRoot: string,
+  targetRoot: string
+): Promise<{ processed: string[]; skipped: FileCheckResult[] }> {
+  if (mode === 'none') {
+    return { processed: [], skipped: [] };
+  }
+
+  const { safe, unsafe } = await getSafeFiles(patterns, sourceRoot);
+  const processed: string[] = [];
+
+  for (const file of safe) {
+    try {
+      if (mode === 'copy') {
+        copyFile(file.path, sourceRoot, targetRoot);
+      } else if (mode === 'symlink') {
+        createSymlink(file.path, sourceRoot, targetRoot);
+      }
+      processed.push(file.path);
+    } catch (error) {
+      // Add to skipped with error reason
+      unsafe.push({
+        ...file,
+        safe: false,
+        reason: `Failed to ${mode}: ${(error as Error).message}`,
+      });
+    }
+  }
+
+  return { processed, skipped: unsafe };
+}

package/src/lib/types.ts

@@ -0,0 +1,69 @@
+/**
+ * VWT Configuration Types
+ */
+
+export interface VwtConfig {
+  /** Base directory for worktrees (optional, defaults to .worktrees/) */
+  worktreeBaseDir?: string;
+  /** Default mode for secrets handling */
+  defaultMode: 'copy' | 'symlink' | 'none';
+  /** List of globs/paths to manage (e.g. [".env", ".env.*", "config/oauth*.json"]) */
+  include: string[];
+  /** Hook commands */
+  hooks?: {
+    postCreate?: string[];
+  };
+  /** Default agent command */
+  agentCommand?: string;
+}
+
+export interface VwtLocalConfig {
+  /** Machine-specific base directory override */
+  worktreeBaseDir?: string;
+  /** Additional include paths for this machine */
+  include?: string[];
+  /** Additional hooks for this machine */
+  hooks?: {
+    postCreate?: string[];
+  };
+  /** Override agent command */
+  agentCommand?: string;
+}
+
+export interface MergedConfig {
+  worktreeBaseDir?: string;
+  defaultMode: 'copy' | 'symlink' | 'none';
+  include: string[];
+  hooks: {
+    postCreate: string[];
+  };
+  agentCommand: string;
+}
+
+export interface WorktreeInfo {
+  worktree: string;
+  head: string;
+  branch?: string;
+  bare?: boolean;
+  detached?: boolean;
+}
+
+export interface WorktreeListItem {
+  branch: string | null;
+  path: string;
+  headShort: string;
+  dirty: boolean;
+  lastModified: Date | null;
+}
+
+export type SecretMode = 'copy' | 'symlink' | 'none';
+
+export interface SpawnOptions {
+  branch: string;
+  isNew: boolean;
+  path?: string;
+  base?: string;
+  mode: SecretMode;
+  run?: string;
+  agent?: 'claude' | 'none';
+}

package/tests/config.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for configuration management
+ */
+
+import { describe, it, expect } from 'vitest';
+import { mergeConfig } from '../src/lib/config.js';
+import type { VwtConfig, VwtLocalConfig } from '../src/lib/types.js';
+
+describe('mergeConfig', () => {
+  const baseConfig: VwtConfig = {
+    defaultMode: 'copy',
+    include: ['.env', '.env.local'],
+    hooks: {
+      postCreate: ['npm install'],
+    },
+    agentCommand: 'claude',
+    worktreeBaseDir: '/default/base',
+  };
+
+  it('returns defaults when both configs are null', () => {
+    const result = mergeConfig(null, null);
+    expect(result.defaultMode).toBe('copy');
+    expect(result.include).toContain('.env');
+    expect(result.agentCommand).toBe('claude');
+  });
+
+  it('uses base config values when no local config', () => {
+    const result = mergeConfig(baseConfig, null);
+    expect(result.defaultMode).toBe('copy');
+    expect(result.include).toEqual(['.env', '.env.local']);
+    expect(result.hooks.postCreate).toEqual(['npm install']);
+    expect(result.agentCommand).toBe('claude');
+    expect(result.worktreeBaseDir).toBe('/default/base');
+  });
+
+  it('merges include arrays from both configs', () => {
+    const localConfig: VwtLocalConfig = {
+      include: ['credentials.json', '.secrets'],
+    };
+    const result = mergeConfig(baseConfig, localConfig);
+    expect(result.include).toEqual(['.env', '.env.local', 'credentials.json', '.secrets']);
+  });
+
+  it('local worktreeBaseDir overrides base', () => {
+    const localConfig: VwtLocalConfig = {
+      worktreeBaseDir: '/custom/local/path',
+    };
+    const result = mergeConfig(baseConfig, localConfig);
+    expect(result.worktreeBaseDir).toBe('/custom/local/path');
+  });
+
+  it('local agentCommand overrides base', () => {
+    const localConfig: VwtLocalConfig = {
+      agentCommand: 'cursor',
+    };
+    const result = mergeConfig(baseConfig, localConfig);
+    expect(result.agentCommand).toBe('cursor');
+  });
+
+  it('merges postCreate hooks from both configs', () => {
+    const localConfig: VwtLocalConfig = {
+      hooks: {
+        postCreate: ['npm run dev', 'code .'],
+      },
+    };
+    const result = mergeConfig(baseConfig, localConfig);
+    expect(result.hooks.postCreate).toEqual(['npm install', 'npm run dev', 'code .']);
+  });
+
+  it('handles empty include arrays', () => {
+    const config: VwtConfig = {
+      defaultMode: 'none',
+      include: [],
+    };
+    const localConfig: VwtLocalConfig = {
+      include: [],
+    };
+    const result = mergeConfig(config, localConfig);
+    expect(result.include).toEqual([]);
+  });
+
+  it('handles missing hooks in configs', () => {
+    const config: VwtConfig = {
+      defaultMode: 'symlink',
+      include: ['.env'],
+    };
+    const result = mergeConfig(config, null);
+    expect(result.hooks.postCreate).toEqual([]);
+  });
+
+  it('preserves defaultMode from base config', () => {
+    const config: VwtConfig = {
+      defaultMode: 'symlink',
+      include: [],
+    };
+    const localConfig: VwtLocalConfig = {
+      include: ['.env'],
+    };
+    const result = mergeConfig(config, localConfig);
+    expect(result.defaultMode).toBe('symlink');
+  });
+});