claude-mycelium 2.0.0 → 2.2.0

package/src/utils/file-utils.ts

@@ -1,6 +1,41 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
+const PROJECT_ROOT = process.cwd();
+const PROTECTED_DIRS = ['.git', 'node_modules'];
+
+/**
+ * Validate file path to prevent path traversal attacks
+ * SECURITY: Ensures path is within project directory and not in protected directories
+ */
+function validatePath(filePath: string): string {
+  // Resolve to absolute path and normalize
+  const absolutePath = path.resolve(filePath);
+  const normalizedPath = path.normalize(absolutePath);
+
+  // Check for null bytes (common attack vector)
+  if (filePath.includes('\0') || normalizedPath.includes('\0')) {
+    throw new Error(`Invalid path: contains null bytes`);
+  }
+
+  // Ensure path is within project directory
+  if (!normalizedPath.startsWith(PROJECT_ROOT)) {
+    throw new Error(`Path traversal detected: ${filePath} is outside project directory`);
+  }
+
+  // Check if path goes into protected directories
+  const relativePath = path.relative(PROJECT_ROOT, normalizedPath);
+  const pathComponents = relativePath.split(path.sep);
+
+  for (const component of pathComponents) {
+    if (PROTECTED_DIRS.includes(component)) {
+      throw new Error(`Access to protected directory denied: ${component}`);
+    }
+  }
+
+  return normalizedPath;
+}
+
 export function pathToSafeFilename(filePath: string): string {
   return filePath.replace(/[/\\]+/g, '__');
 }
@@ -11,7 +46,8 @@ export function safeFilenameToPath(safeFilename: string): string {
 
 export function fileExists(filePath: string): boolean {
   try {
-    fs.accessSync(filePath, fs.constants.F_OK);
+    const safePath = validatePath(filePath);
+    fs.accessSync(safePath, fs.constants.F_OK);
     return true;
   } catch {
     return false;
@@ -19,23 +55,26 @@ export function fileExists(filePath: string): boolean {
 }
 
 export function readFile(filePath: string): string {
-  return fs.readFileSync(filePath, 'utf-8');
+  const safePath = validatePath(filePath);
+  return fs.readFileSync(safePath, 'utf-8');
 }
 
 export function writeFile(filePath: string, content: string): void {
-  const dir = path.dirname(filePath);
+  const safePath = validatePath(filePath);
+  const dir = path.dirname(safePath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  fs.writeFileSync(filePath, content, 'utf-8');
+  fs.writeFileSync(safePath, content, 'utf-8');
 }
 
 export function appendFile(filePath: string, content: string): void {
-  const dir = path.dirname(filePath);
+  const safePath = validatePath(filePath);
+  const dir = path.dirname(safePath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  fs.appendFileSync(filePath, content, 'utf-8');
+  fs.appendFileSync(safePath, content, 'utf-8');
 }
 
 export function readJsonFile<T>(filePath: string): T {
@@ -49,6 +88,7 @@ export function writeJsonFile<T>(filePath: string, data: T, indent: number = 2):
 }
 
 export function listFilesRecursive(dirPath: string): string[] {
+  const safePath = validatePath(dirPath);
   const files: string[] = [];
 
   function traverse(currentPath: string): void {
@@ -63,7 +103,7 @@ export function listFilesRecursive(dirPath: string): string[] {
     }
   }
 
-  traverse(dirPath);
+  traverse(safePath);
   return files;
 }
 
@@ -81,31 +121,37 @@ export function isTestFile(filePath: string): boolean {
 }
 
 export function ensureDir(dirPath: string): void {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
+  const safePath = validatePath(dirPath);
+  if (!fs.existsSync(safePath)) {
+    fs.mkdirSync(safePath, { recursive: true });
   }
 }
 
 export function deleteFile(filePath: string): void {
-  if (fileExists(filePath)) {
-    fs.unlinkSync(filePath);
+  const safePath = validatePath(filePath);
+  if (fs.existsSync(safePath)) {
+    fs.unlinkSync(safePath);
   }
 }
 
 export function copyFile(sourcePath: string, destPath: string): void {
-  const dir = path.dirname(destPath);
+  const safeSrc = validatePath(sourcePath);
+  const safeDest = validatePath(destPath);
+  const dir = path.dirname(safeDest);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  fs.copyFileSync(sourcePath, destPath);
+  fs.copyFileSync(safeSrc, safeDest);
 }
 
 export function getFileModTime(filePath: string): number {
-  const stats = fs.statSync(filePath);
+  const safePath = validatePath(filePath);
+  const stats = fs.statSync(safePath);
   return stats.mtimeMs;
 }
 
 export function getFileSize(filePath: string): number {
-  const stats = fs.statSync(filePath);
+  const safePath = validatePath(filePath);
+  const stats = fs.statSync(safePath);
   return stats.size;
 }

package/tests/cli/gc.test.ts

@@ -0,0 +1,206 @@
+/**
+ * GC CLI Command Tests
+ *
+ * Tests for garbage collection command
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { fileExists } from '../../src/utils/file-utils.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Use a temporary test directory
+const testDir = path.join(__dirname, '../../.test-gc');
+
+describe('GC Command', () => {
+  beforeEach(async () => {
+    // Clean up test directory
+    if (fileExists(testDir)) {
+      await fs.rm(testDir, { recursive: true });
+    }
+    await fs.mkdir(testDir, { recursive: true });
+    await fs.mkdir(path.join(testDir, '.agent-meta'), { recursive: true });
+    await fs.mkdir(path.join(testDir, '.agent-meta/traces'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    if (fileExists(testDir)) {
+      await fs.rm(testDir, { recursive: true });
+    }
+  });
+
+  it('should handle empty traces directory', async () => {
+    const tracesDir = path.join(testDir, '.agent-meta/traces');
+    expect(fileExists(tracesDir)).toBe(true);
+
+    // Verify directory is empty
+    const entries = await fs.readdir(tracesDir);
+    expect(entries).toHaveLength(0);
+  });
+
+  it('should create GC log file', async () => {
+    const gcLogPath = path.join(testDir, '.agent-meta/_gc.log');
+
+    // Create GC log
+    await fs.writeFile(gcLogPath, '');
+
+    expect(fileExists(gcLogPath)).toBe(true);
+  });
+
+  it('should append GC reports to log', async () => {
+    const gcLogPath = path.join(testDir, '.agent-meta/_gc.log');
+
+    const report1 = {
+      timestamp: new Date().toISOString(),
+      deleted: 10,
+      compacted: 2,
+      size_before_mb: 50,
+      size_after_mb: 45,
+      errors: [],
+      duration_ms: 1000,
+    };
+
+    const report2 = {
+      timestamp: new Date(Date.now() + 1000).toISOString(),
+      deleted: 5,
+      compacted: 1,
+      size_before_mb: 45,
+      size_after_mb: 43,
+      errors: [],
+      duration_ms: 800,
+    };
+
+    // Append reports
+    await fs.appendFile(gcLogPath, JSON.stringify(report1) + '\n');
+    await fs.appendFile(gcLogPath, JSON.stringify(report2) + '\n');
+
+    const content = await fs.readFile(gcLogPath, 'utf-8');
+    const lines = content.split('\n').filter(Boolean);
+
+    expect(lines).toHaveLength(2);
+
+    const loaded1 = JSON.parse(lines[0]);
+    const loaded2 = JSON.parse(lines[1]);
+
+    expect(loaded1.deleted).toBe(10);
+    expect(loaded2.deleted).toBe(5);
+  });
+
+  it('should calculate space saved correctly', () => {
+    const report = {
+      timestamp: new Date().toISOString(),
+      deleted: 10,
+      compacted: 2,
+      size_before_mb: 50,
+      size_after_mb: 45,
+      errors: [],
+      duration_ms: 1000,
+    };
+
+    const saved = report.size_before_mb - report.size_after_mb;
+    const percent = (saved / report.size_before_mb) * 100;
+
+    expect(saved).toBe(5);
+    expect(percent).toBeCloseTo(10);
+  });
+
+  it('should handle GC with errors', async () => {
+    const gcLogPath = path.join(testDir, '.agent-meta/_gc.log');
+
+    const report = {
+      timestamp: new Date().toISOString(),
+      deleted: 5,
+      compacted: 1,
+      size_before_mb: 45,
+      size_after_mb: 43,
+      errors: [
+        'file1.ndjson: permission denied',
+        'file2.ndjson: parse error on line 5',
+      ],
+      duration_ms: 500,
+    };
+
+    await fs.appendFile(gcLogPath, JSON.stringify(report) + '\n');
+
+    const content = await fs.readFile(gcLogPath, 'utf-8');
+    const loaded = JSON.parse(content);
+
+    expect(loaded.errors).toHaveLength(2);
+    expect(loaded.errors[0]).toContain('permission denied');
+  });
+
+  it('should read GC history', async () => {
+    const gcLogPath = path.join(testDir, '.agent-meta/_gc.log');
+
+    // Create multiple GC reports
+    for (let i = 0; i < 5; i++) {
+      const report = {
+        timestamp: new Date(Date.now() - i * 1000000).toISOString(),
+        deleted: 10 + i,
+        compacted: 2,
+        size_before_mb: 50 - i,
+        size_after_mb: 45 - i,
+        errors: [],
+        duration_ms: 1000,
+      };
+
+      await fs.appendFile(gcLogPath, JSON.stringify(report) + '\n');
+    }
+
+    const content = await fs.readFile(gcLogPath, 'utf-8');
+    const lines = content.split('\n').filter(Boolean);
+
+    expect(lines).toHaveLength(5);
+
+    const reports = lines.map(l => JSON.parse(l));
+    const totalDeleted = reports.reduce((sum: number, r: any) => sum + r.deleted, 0);
+
+    expect(totalDeleted).toBe(50 + 10); // 10+11+12+13+14
+  });
+
+  it('should track total space saved', async () => {
+    const gcLogPath = path.join(testDir, '.agent-meta/_gc.log');
+
+    const reports = [
+      {
+        timestamp: new Date().toISOString(),
+        deleted: 10,
+        compacted: 2,
+        size_before_mb: 100,
+        size_after_mb: 90,
+        errors: [],
+        duration_ms: 1000,
+      },
+      {
+        timestamp: new Date(Date.now() + 1000).toISOString(),
+        deleted: 8,
+        compacted: 1,
+        size_before_mb: 90,
+        size_after_mb: 85,
+        errors: [],
+        duration_ms: 900,
+      },
+    ];
+
+    for (const report of reports) {
+      await fs.appendFile(gcLogPath, JSON.stringify(report) + '\n');
+    }
+
+    const content = await fs.readFile(gcLogPath, 'utf-8');
+    const lines = content.split('\n').filter(Boolean);
+    const loaded = lines.map(l => JSON.parse(l));
+
+    const totalSaved = loaded.reduce(
+      (sum: number, r: any) => sum + (r.size_before_mb - r.size_after_mb),
+      0
+    );
+
+    expect(totalSaved).toBe(15); // (100-90) + (90-85)
+  });
+});

package/tests/cli/init.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Init CLI Command Tests
+ *
+ * Tests for .agent-meta/ initialization
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { fileExists } from '../../src/utils/file-utils.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Use a temporary test directory
+const testDir = path.join(__dirname, '../../.test-init');
+
+describe('Init Command', () => {
+  beforeEach(async () => {
+    // Clean up test directory
+    if (fileExists(testDir)) {
+      await fs.rm(testDir, { recursive: true });
+    }
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    if (fileExists(testDir)) {
+      await fs.rm(testDir, { recursive: true });
+    }
+  });
+
+  it('should create .agent-meta directory structure', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+
+    // Create subdirectories
+    await fs.mkdir(metaDir, { recursive: true });
+    await fs.mkdir(path.join(metaDir, 'traces'), { recursive: true });
+    await fs.mkdir(path.join(metaDir, 'tasks'), { recursive: true });
+    await fs.mkdir(path.join(metaDir, 'locks'), { recursive: true });
+
+    expect(fileExists(metaDir)).toBe(true);
+    expect(fileExists(path.join(metaDir, 'traces'))).toBe(true);
+    expect(fileExists(path.join(metaDir, 'tasks'))).toBe(true);
+    expect(fileExists(path.join(metaDir, 'locks'))).toBe(true);
+  });
+
+  it('should create _config.json with default values', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+    await fs.mkdir(metaDir, { recursive: true });
+
+    const configPath = path.join(metaDir, '_config.json');
+    const config = {
+      version: '2.0.0',
+      created_at: new Date().toISOString(),
+      error_provider: 'file',
+      error_file: '.agent-meta/_errors.json',
+      ci_command: 'npm test && npm run lint',
+      spawn_count: 0,
+      last_gc_at_spawn: 0,
+    };
+
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    expect(fileExists(configPath)).toBe(true);
+
+    const content = await fs.readFile(configPath, 'utf-8');
+    const loaded = JSON.parse(content);
+
+    expect(loaded.version).toBe('2.0.0');
+    expect(loaded.spawn_count).toBe(0);
+    expect(loaded.error_provider).toBe('file');
+  });
+
+  it('should create _quarantine.json with empty entries', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+    await fs.mkdir(metaDir, { recursive: true });
+
+    const quarantinePath = path.join(metaDir, '_quarantine.json');
+    const quarantine = {
+      updated_at: new Date().toISOString(),
+      entries: [],
+    };
+
+    await fs.writeFile(quarantinePath, JSON.stringify(quarantine, null, 2));
+
+    expect(fileExists(quarantinePath)).toBe(true);
+
+    const content = await fs.readFile(quarantinePath, 'utf-8');
+    const loaded = JSON.parse(content);
+
+    expect(loaded.entries).toEqual([]);
+    expect(loaded.updated_at).toBeDefined();
+  });
+
+  it('should create _inhibitors.ndjson as empty file', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+    await fs.mkdir(metaDir, { recursive: true });
+
+    const inhibitorsPath = path.join(metaDir, '_inhibitors.ndjson');
+    await fs.writeFile(inhibitorsPath, '');
+
+    expect(fileExists(inhibitorsPath)).toBe(true);
+
+    const content = await fs.readFile(inhibitorsPath, 'utf-8');
+    expect(content).toBe('');
+  });
+
+  it('should create _errors.json with empty errors', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+    await fs.mkdir(metaDir, { recursive: true });
+
+    const errorsPath = path.join(metaDir, '_errors.json');
+    const errors = {
+      updated_at: new Date().toISOString(),
+      errors: [],
+    };
+
+    await fs.writeFile(errorsPath, JSON.stringify(errors, null, 2));
+
+    expect(fileExists(errorsPath)).toBe(true);
+
+    const content = await fs.readFile(errorsPath, 'utf-8');
+    const loaded = JSON.parse(content);
+
+    expect(loaded.errors).toEqual([]);
+  });
+
+  it('should create _gc.log as empty file', async () => {
+    const metaDir = path.join(testDir, '.agent-meta');
+    await fs.mkdir(metaDir, { recursive: true });
+
+    const gcLogPath = path.join(metaDir, '_gc.log');
+    await fs.writeFile(gcLogPath, '');
+
+    expect(fileExists(gcLogPath)).toBe(true);
+
+    const content = await fs.readFile(gcLogPath, 'utf-8');
+    expect(content).toBe('');
+  });
+
+  it('should update .gitignore with locks pattern', async () => {
+    const gitignorePath = path.join(testDir, '.gitignore');
+    const metaDir = path.join(testDir, '.agent-meta');
+    const lockPattern = '.agent-meta/locks/';
+
+    // Create .gitignore
+    await fs.writeFile(gitignorePath, '# Test\n');
+
+    // Check and update
+    const content = await fs.readFile(gitignorePath, 'utf-8');
+    if (!content.includes(lockPattern)) {
+      await fs.appendFile(
+        gitignorePath,
+        `\n# Claude Mycelium locks (ephemeral)\n${lockPattern}\n`
+      );
+    }
+
+    const updated = await fs.readFile(gitignorePath, 'utf-8');
+    expect(updated).toContain(lockPattern);
+  });
+
+  it('should create .gitignore if it does not exist', async () => {
+    const gitignorePath = path.join(testDir, '.gitignore');
+    const lockPattern = '.agent-meta/locks/';
+
+    // Create .gitignore with the pattern
+    await fs.writeFile(
+      gitignorePath,
+      `# Claude Mycelium locks (ephemeral)\n${lockPattern}\n`
+    );
+
+    expect(fileExists(gitignorePath)).toBe(true);
+
+    const content = await fs.readFile(gitignorePath, 'utf-8');
+    expect(content).toContain(lockPattern);
+  });
+});