claude-mycelium 2.0.0

package/src/utils/ci-provider.ts

@@ -0,0 +1,145 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import type { CIProvider, ChangeSet } from '../types/index.js';
+import { loadConfig } from './config.js';
+import { logInfo, logError } from './logger.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * CI provider that runs tests and linters
+ * Per spec §16 (second-spec.md)
+ *
+ * Default command: "npm test && npm run lint"
+ * Configurable via .agent-meta/config.json
+ */
+export class NpmCIProvider implements CIProvider {
+  private ciCommand: string;
+
+  constructor(ciCommand?: string) {
+    if (ciCommand) {
+      this.ciCommand = ciCommand;
+    } else {
+      // Load from config
+      const config = loadConfig();
+      this.ciCommand = config.ci_command;
+    }
+  }
+
+  /**
+   * Run CI checks (tests + lint)
+   * Returns whether all checks passed and output
+   */
+  async run(changes: ChangeSet): Promise<{ passed: boolean; output: string }> {
+    logInfo('Running CI checks', {
+      command: this.ciCommand,
+      files: changes.files_touched.length,
+    });
+
+    try {
+      const { stdout, stderr } = await execAsync(this.ciCommand, {
+        maxBuffer: 1024 * 1024 * 10, // 10MB buffer for large test output
+        timeout: 300000, // 5 minute timeout
+      });
+
+      const output = [stdout, stderr].filter(Boolean).join('\n');
+
+      logInfo('CI checks passed', {
+        additions: changes.additions,
+        deletions: changes.deletions,
+      });
+
+      return {
+        passed: true,
+        output,
+      };
+    } catch (error: any) {
+      // exec throws error when command exits with non-zero code
+      const output = [error.stdout || '', error.stderr || '']
+        .filter(Boolean)
+        .join('\n');
+
+      logError('CI checks failed', error, {
+        exitCode: error.code,
+        signal: error.signal,
+      });
+
+      return {
+        passed: false,
+        output: output || error.message,
+      };
+    }
+  }
+
+  /**
+   * Run only tests (skip lint)
+   */
+  async runTests(): Promise<{ passed: boolean; output: string }> {
+    const testCommand = 'npm test';
+
+    try {
+      const { stdout, stderr } = await execAsync(testCommand, {
+        maxBuffer: 1024 * 1024 * 10,
+        timeout: 300000,
+      });
+
+      return {
+        passed: true,
+        output: [stdout, stderr].filter(Boolean).join('\n'),
+      };
+    } catch (error: any) {
+      return {
+        passed: false,
+        output:
+          [error.stdout, error.stderr].filter(Boolean).join('\n') ||
+          error.message,
+      };
+    }
+  }
+
+  /**
+   * Run only lint (skip tests)
+   */
+  async runLint(): Promise<{ passed: boolean; output: string }> {
+    const lintCommand = 'npm run lint';
+
+    try {
+      const { stdout, stderr } = await execAsync(lintCommand, {
+        maxBuffer: 1024 * 1024 * 10,
+        timeout: 60000, // 1 minute for lint
+      });
+
+      return {
+        passed: true,
+        output: [stdout, stderr].filter(Boolean).join('\n'),
+      };
+    } catch (error: any) {
+      return {
+        passed: false,
+        output:
+          [error.stdout, error.stderr].filter(Boolean).join('\n') ||
+          error.message,
+      };
+    }
+  }
+
+  /**
+   * Check if CI is configured (npm scripts exist)
+   */
+  async isConfigured(): Promise<boolean> {
+    try {
+      // Check if npm test is defined
+      await execAsync('npm run test --help', {
+        timeout: 5000,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Default CI provider instance
+ */
+export const ciProvider = new NpmCIProvider();

package/src/utils/config.ts

@@ -0,0 +1,95 @@
+import { fileExists, readJsonFile, writeJsonFile } from './file-utils.js';
+import type { SystemConfig } from '../types/index.js';
+
+const CONFIG_PATH = '.agent-meta/config.json';
+
+/**
+ * Default configuration per spec §13
+ */
+export const DEFAULT_CONFIG: SystemConfig = {
+  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,
+};
+
+/**
+ * Load configuration from .agent-meta/config.json
+ * Creates default config if file doesn't exist
+ */
+export function loadConfig(): SystemConfig {
+  if (!fileExists(CONFIG_PATH)) {
+    // Initialize with defaults
+    writeJsonFile(CONFIG_PATH, DEFAULT_CONFIG);
+    return DEFAULT_CONFIG;
+  }
+
+  try {
+    const config = readJsonFile<SystemConfig>(CONFIG_PATH);
+
+    // Merge with defaults to handle missing fields
+    return {
+      ...DEFAULT_CONFIG,
+      ...config,
+    };
+  } catch (error) {
+    console.error(`Failed to load config from ${CONFIG_PATH}:`, error);
+    console.error('Using default configuration');
+    return DEFAULT_CONFIG;
+  }
+}
+
+/**
+ * Save configuration to .agent-meta/config.json
+ */
+export function saveConfig(config: SystemConfig): void {
+  try {
+    writeJsonFile(CONFIG_PATH, config);
+  } catch (error) {
+    console.error(`Failed to save config to ${CONFIG_PATH}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Update specific config fields
+ */
+export function updateConfig(updates: Partial<SystemConfig>): SystemConfig {
+  const config = loadConfig();
+  const updated = {
+    ...config,
+    ...updates,
+  };
+  saveConfig(updated);
+  return updated;
+}
+
+/**
+ * Increment spawn counter and check if GC should run
+ * GC runs every 100 spawns (per spec §8)
+ */
+export function incrementSpawnCount(): { count: number; shouldRunGC: boolean } {
+  const config = loadConfig();
+  config.spawn_count += 1;
+
+  const shouldRunGC = config.spawn_count - config.last_gc_at_spawn >= 100;
+
+  saveConfig(config);
+
+  return {
+    count: config.spawn_count,
+    shouldRunGC,
+  };
+}
+
+/**
+ * Mark that GC has been run
+ */
+export function markGCRun(): void {
+  const config = loadConfig();
+  config.last_gc_at_spawn = config.spawn_count;
+  saveConfig(config);
+}

package/src/utils/error-provider.ts

@@ -0,0 +1,138 @@
+import { fileExists, readJsonFile, writeJsonFile } from './file-utils.js';
+import type { ErrorProvider, ErrorProviderData } from '../types/index.js';
+import { logWarn } from './logger.js';
+
+const ERROR_FILE_PATH = '.agent-meta/_errors.json';
+
+/**
+ * File-based error provider implementation
+ * Per spec §2.5 (second-spec.md lines 665-705)
+ *
+ * Users populate .agent-meta/_errors.json manually or via external tools
+ * Format:
+ * {
+ *   "updated_at": "2026-01-30T17:00:00Z",
+ *   "errors": [
+ *     {
+ *       "file": "src/auth.ts",
+ *       "count": 6,
+ *       "types": ["TypeError", "ReferenceError"]
+ *     }
+ *   ]
+ * }
+ */
+export class FileErrorProvider implements ErrorProvider {
+  private errorFilePath: string;
+
+  constructor(errorFilePath: string = ERROR_FILE_PATH) {
+    this.errorFilePath = errorFilePath;
+  }
+
+  /**
+   * Get error count and types for a specific file
+   */
+  async getErrors(file: string): Promise<{ count: number; types: string[] }> {
+    if (!fileExists(this.errorFilePath)) {
+      // No error file exists - return zero errors
+      return { count: 0, types: [] };
+    }
+
+    try {
+      const data = readJsonFile<ErrorProviderData>(this.errorFilePath);
+
+      const entry = data.errors.find((e) => e.file === file);
+
+      if (!entry) {
+        return { count: 0, types: [] };
+      }
+
+      return {
+        count: entry.count,
+        types: entry.types,
+      };
+    } catch (error) {
+      logWarn(`Failed to read error file: ${this.errorFilePath}`, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return { count: 0, types: [] };
+    }
+  }
+
+  /**
+   * Initialize error file with empty data
+   */
+  initializeErrorFile(): void {
+    if (!fileExists(this.errorFilePath)) {
+      const initialData: ErrorProviderData = {
+        updated_at: new Date().toISOString(),
+        errors: [],
+      };
+      writeJsonFile(this.errorFilePath, initialData);
+    }
+  }
+
+  /**
+   * Update errors for a specific file
+   * Helper for manual error tracking
+   */
+  updateErrors(file: string, count: number, types: string[]): void {
+    let data: ErrorProviderData;
+
+    if (fileExists(this.errorFilePath)) {
+      data = readJsonFile<ErrorProviderData>(this.errorFilePath);
+    } else {
+      data = {
+        updated_at: new Date().toISOString(),
+        errors: [],
+      };
+    }
+
+    // Update or add entry
+    const existingIndex = data.errors.findIndex((e) => e.file === file);
+
+    if (existingIndex >= 0) {
+      data.errors[existingIndex] = { file, count, types };
+    } else {
+      data.errors.push({ file, count, types });
+    }
+
+    data.updated_at = new Date().toISOString();
+
+    writeJsonFile(this.errorFilePath, data);
+  }
+
+  /**
+   * Clear all error data
+   */
+  clearErrors(): void {
+    const data: ErrorProviderData = {
+      updated_at: new Date().toISOString(),
+      errors: [],
+    };
+    writeJsonFile(this.errorFilePath, data);
+  }
+
+  /**
+   * Get all errors (for reporting)
+   */
+  getAllErrors(): ErrorProviderData['errors'] {
+    if (!fileExists(this.errorFilePath)) {
+      return [];
+    }
+
+    try {
+      const data = readJsonFile<ErrorProviderData>(this.errorFilePath);
+      return data.errors;
+    } catch (error) {
+      logWarn(`Failed to read error file: ${this.errorFilePath}`, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return [];
+    }
+  }
+}
+
+/**
+ * Default error provider instance
+ */
+export const errorProvider = new FileErrorProvider();

package/src/utils/file-utils.ts

@@ -0,0 +1,111 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function pathToSafeFilename(filePath: string): string {
+  return filePath.replace(/[/\\]+/g, '__');
+}
+
+export function safeFilenameToPath(safeFilename: string): string {
+  return safeFilename.replace(/__/g, '/');
+}
+
+export function fileExists(filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readFile(filePath: string): string {
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+export function writeFile(filePath: string, content: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+export function appendFile(filePath: string, content: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.appendFileSync(filePath, content, 'utf-8');
+}
+
+export function readJsonFile<T>(filePath: string): T {
+  const content = readFile(filePath);
+  return JSON.parse(content);
+}
+
+export function writeJsonFile<T>(filePath: string, data: T, indent: number = 2): void {
+  const content = JSON.stringify(data, null, indent);
+  writeFile(filePath, content);
+}
+
+export function listFilesRecursive(dirPath: string): string[] {
+  const files: string[] = [];
+
+  function traverse(currentPath: string): void {
+    const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        traverse(fullPath);
+      } else {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  traverse(dirPath);
+  return files;
+}
+
+export function getLineCount(filePath: string): number {
+  const content = readFile(filePath);
+  return content.split('\n').length;
+}
+
+export function isTypeScriptFile(filePath: string): boolean {
+  return /\.ts$/.test(filePath) && !/\.d\.ts$/.test(filePath);
+}
+
+export function isTestFile(filePath: string): boolean {
+  return /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(filePath);
+}
+
+export function ensureDir(dirPath: string): void {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+export function deleteFile(filePath: string): void {
+  if (fileExists(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+}
+
+export function copyFile(sourcePath: string, destPath: string): void {
+  const dir = path.dirname(destPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.copyFileSync(sourcePath, destPath);
+}
+
+export function getFileModTime(filePath: string): number {
+  const stats = fs.statSync(filePath);
+  return stats.mtimeMs;
+}
+
+export function getFileSize(filePath: string): number {
+  const stats = fs.statSync(filePath);
+  return stats.size;
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for Claude-Mycelium
+ * Centralized exports for cleaner imports
+ */
+
+export * from './file-utils.js';
+export * from './config.js';
+export * from './logger.js';
+export * from './error-provider.js';
+export * from './ci-provider.js';

package/src/utils/logger.ts

@@ -0,0 +1,94 @@
+/**
+ * Structured logging utility for Claude-Mycelium
+ * Simple console-based logging with timestamp and context
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+interface LogContext {
+  [key: string]: unknown;
+}
+
+const LOG_LEVEL: LogLevel = (process.env.LOG_LEVEL as LogLevel) || 'info';
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[LOG_LEVEL];
+}
+
+function formatTimestamp(): string {
+  return new Date().toISOString();
+}
+
+function formatMessage(level: LogLevel, message: string, context?: LogContext): string {
+  const timestamp = formatTimestamp();
+  const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+  return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`;
+}
+
+/**
+ * Log debug message (lowest priority)
+ */
+export function logDebug(message: string, context?: LogContext): void {
+  if (shouldLog('debug')) {
+    console.debug(formatMessage('debug', message, context));
+  }
+}
+
+/**
+ * Log info message (normal priority)
+ */
+export function logInfo(message: string, context?: LogContext): void {
+  if (shouldLog('info')) {
+    console.info(formatMessage('info', message, context));
+  }
+}
+
+/**
+ * Log warning message (high priority)
+ */
+export function logWarn(message: string, context?: LogContext): void {
+  if (shouldLog('warn')) {
+    console.warn(formatMessage('warn', message, context));
+  }
+}
+
+/**
+ * Log error message (highest priority)
+ */
+export function logError(message: string, error?: Error, context?: LogContext): void {
+  if (shouldLog('error')) {
+    const errorContext = error
+      ? {
+          ...context,
+          error: error.message,
+          stack: error.stack,
+        }
+      : context;
+
+    console.error(formatMessage('error', message, errorContext));
+  }
+}
+
+/**
+ * Create a child logger with fixed context
+ * Useful for agent-specific or file-specific logging
+ */
+export function createLogger(baseContext: LogContext) {
+  return {
+    debug: (message: string, context?: LogContext) =>
+      logDebug(message, { ...baseContext, ...context }),
+    info: (message: string, context?: LogContext) =>
+      logInfo(message, { ...baseContext, ...context }),
+    warn: (message: string, context?: LogContext) =>
+      logWarn(message, { ...baseContext, ...context }),
+    error: (message: string, error?: Error, context?: LogContext) =>
+      logError(message, error, { ...baseContext, ...context }),
+  };
+}

package/test-8d713cc8-f4b7-403d-8153-57573172b94c.ts

@@ -0,0 +1,3 @@
+function add(a: number, b: number): number {
+  return a + b;
+}