@nemus-cli/nemus 0.2.1

package/src/utils/github.ts

@@ -0,0 +1,74 @@
+import { exec, execFile } from 'child_process';
+import { promisify } from 'util';
+import { GitHubRepo } from '../types';
+import { logError, logInfo } from './logger';
+import { getCachedRepos, setCachedRepos } from './cache';
+import { getUserConfig } from './config';
+
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+
+export const verifyGhAuth = async (): Promise<boolean> => {
+  try {
+    const { stdout } = await execAsync('gh auth status');
+    return stdout.includes('Logged in') || stdout.includes('✓');
+  } catch (error) {
+    return false;
+  }
+};
+
+export const fetchOrgRepos = async (options: { forceRefresh?: boolean } = {}): Promise<GitHubRepo[]> => {
+  const { forceRefresh = false } = options;
+
+  try {
+    const { githubOrg } = getUserConfig();
+
+    // Try to get cached repos first
+    if (!forceRefresh) {
+      const cachedRepos = await getCachedRepos({ org: githubOrg });
+      if (cachedRepos) {
+        return cachedRepos.sort((a, b) => a.name.localeCompare(b.name));
+      }
+    }
+    logInfo(
+      githubOrg
+        ? `Fetching ${githubOrg} repositories from GitHub...`
+        : 'Fetching your GitHub repositories... (set an org with `nemus configure` to list an organization)'
+    );
+
+    // With no configured org, `gh repo list` (no positional) lists the
+    // authenticated user's own repos. With an org, it lists that org's repos.
+    const args = [
+      'repo', 'list',
+      ...(githubOrg ? [githubOrg] : []),
+      '--limit', '1000',
+      '--json', 'name,url,sshUrl,owner,description,isPrivate',
+    ];
+    const { stdout } = await execFileAsync('gh', args);
+
+    const repos: GitHubRepo[] = JSON.parse(stdout);
+
+    logInfo(`Found ${repos.length} repositories`);
+
+    // Cache the results (24 hour TTL)
+    await setCachedRepos(repos, 86400000, githubOrg);
+
+    return repos.sort((a, b) => a.name.localeCompare(b.name));
+  } catch (error) {
+    logError('Failed to fetch repositories from GitHub');
+    if (error instanceof Error) {
+      logError(error.message);
+    }
+    throw new Error('Unable to fetch repositories. Please ensure gh CLI is authenticated.');
+  }
+};
+
+export const displayAuthInstructions = (): void => {
+  console.log('\n' + '='.repeat(60));
+  console.log('GitHub CLI Authentication Required');
+  console.log('='.repeat(60));
+  console.log('\nPlease authenticate with GitHub CLI by running:');
+  console.log('\n  gh auth login\n');
+  console.log('Then try running this command again.');
+  console.log('='.repeat(60) + '\n');
+};

package/src/utils/health-checks.ts

@@ -0,0 +1,359 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { HealthCheckResult, WorkspaceMetadata } from '../types';
+import { isGitRepository, hasUncommittedChanges } from './git-status';
+
+const execAsync = promisify(exec);
+
+export const checkMissingRepositories = async (
+  workspacePath: string,
+  metadata: WorkspaceMetadata
+): Promise<HealthCheckResult> => {
+  const missingRepos: string[] = [];
+
+  for (const repo of metadata.repositories) {
+    const repoPath = path.join(workspacePath, repo.directoryName);
+    try {
+      await fs.access(repoPath);
+    } catch {
+      missingRepos.push(repo.directoryName);
+    }
+  }
+
+  if (missingRepos.length === 0) {
+    return {
+      category: 'Missing Repositories',
+      status: 'healthy',
+      message: 'All repositories are present',
+    };
+  }
+
+  return {
+    category: 'Missing Repositories',
+    status: 'error',
+    message: `${missingRepos.length} repository(ies) missing`,
+    details: missingRepos.join(', '),
+    actionable: `Run 'workspace sync ${metadata.workspaceName}' to clone missing repositories`,
+  };
+};
+
+export const checkGitHealth = async (
+  workspacePath: string,
+  repoNames: string[]
+): Promise<HealthCheckResult> => {
+  const issues: string[] = [];
+
+  for (const repoName of repoNames) {
+    const repoPath = path.join(workspacePath, repoName);
+
+    try {
+      await fs.access(repoPath);
+    } catch {
+      continue; // Skip missing repos (handled by checkMissingRepositories)
+    }
+
+    const isRepo = await isGitRepository(repoPath);
+    if (!isRepo) {
+      issues.push(`${repoName}: not a git repository`);
+      continue;
+    }
+
+    // Check for corrupted repo
+    try {
+      await execAsync('git fsck --no-progress', {
+        cwd: repoPath,
+        timeout: 30000,
+      });
+    } catch (error) {
+      issues.push(`${repoName}: repository may be corrupted`);
+    }
+  }
+
+  if (issues.length === 0) {
+    return {
+      category: 'Git Health',
+      status: 'healthy',
+      message: 'All repositories are healthy',
+    };
+  }
+
+  return {
+    category: 'Git Health',
+    status: 'error',
+    message: `${issues.length} repository(ies) have issues`,
+    details: issues.join('\n'),
+    actionable: 'Check repository integrity and consider re-cloning problematic repos',
+  };
+};
+
+export const checkUncommittedChanges = async (
+  workspacePath: string,
+  repoNames: string[]
+): Promise<HealthCheckResult> => {
+  const dirtyRepos: string[] = [];
+
+  for (const repoName of repoNames) {
+    const repoPath = path.join(workspacePath, repoName);
+
+    try {
+      await fs.access(repoPath);
+    } catch {
+      continue;
+    }
+
+    const hasChanges = await hasUncommittedChanges(repoPath);
+    if (hasChanges) {
+      dirtyRepos.push(repoName);
+    }
+  }
+
+  if (dirtyRepos.length === 0) {
+    return {
+      category: 'Uncommitted Changes',
+      status: 'healthy',
+      message: 'No uncommitted changes',
+    };
+  }
+
+  return {
+    category: 'Uncommitted Changes',
+    status: 'warning',
+    message: `${dirtyRepos.length} repository(ies) have uncommitted changes`,
+    details: dirtyRepos.join(', '),
+    actionable: `Review and commit or stash changes before switching branches`,
+  };
+};
+
+export const checkAuthentication = async (): Promise<HealthCheckResult> => {
+  const issues: string[] = [];
+
+  // Check GitHub CLI
+  try {
+    await execAsync('gh auth status', { timeout: 5000 });
+  } catch {
+    issues.push('GitHub CLI (gh) not authenticated');
+  }
+
+  // Check SSH keys
+  try {
+    await execAsync('ssh -T git@github.com', { timeout: 5000 });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : '';
+    if (!errorMessage.includes('successfully authenticated')) {
+      issues.push('SSH key not configured for GitHub');
+    }
+  }
+
+  if (issues.length === 0) {
+    return {
+      category: 'Authentication',
+      status: 'healthy',
+      message: 'Authentication configured correctly',
+    };
+  }
+
+  return {
+    category: 'Authentication',
+    status: 'warning',
+    message: 'Authentication issues detected',
+    details: issues.join('\n'),
+    actionable: 'Run "gh auth login" or configure SSH keys',
+  };
+};
+
+export const checkDependencies = async (
+  workspacePath: string,
+  repoNames: string[]
+): Promise<HealthCheckResult> => {
+  const missingDeps: string[] = [];
+
+  for (const repoName of repoNames) {
+    const repoPath = path.join(workspacePath, repoName);
+
+    try {
+      await fs.access(repoPath);
+    } catch {
+      continue;
+    }
+
+    // Check for package.json
+    const packageJsonPath = path.join(repoPath, 'package.json');
+    try {
+      await fs.access(packageJsonPath);
+
+      // Check if node_modules exists
+      const nodeModulesPath = path.join(repoPath, 'node_modules');
+      try {
+        await fs.access(nodeModulesPath);
+      } catch {
+        missingDeps.push(`${repoName}: missing node_modules`);
+      }
+    } catch {
+      // No package.json, skip
+    }
+  }
+
+  if (missingDeps.length === 0) {
+    return {
+      category: 'Dependencies',
+      status: 'healthy',
+      message: 'All dependencies installed',
+    };
+  }
+
+  return {
+    category: 'Dependencies',
+    status: 'warning',
+    message: `${missingDeps.length} repository(ies) missing dependencies`,
+    details: missingDeps.join('\n'),
+    actionable: 'Run "npm install" or "yarn install" in affected repositories',
+  };
+};
+
+export const checkDiskSpace = async (workspacePath: string): Promise<HealthCheckResult> => {
+  try {
+    // Get disk usage for workspace
+    const { stdout } = await execAsync(`du -sh "${workspacePath}"`, { timeout: 30000 });
+    const sizeStr = stdout.trim().split('\t')[0];
+
+    // Parse size (rough check for > 10GB)
+    const sizeValue = parseFloat(sizeStr);
+    const unit = sizeStr.replace(/[0-9.]/g, '').trim();
+
+    const isLarge = (unit === 'G' && sizeValue > 10) || unit === 'T';
+
+    if (isLarge) {
+      return {
+        category: 'Disk Space',
+        status: 'warning',
+        message: `Workspace is large (${sizeStr})`,
+        actionable: 'Consider running "workspace cleanup" to free up space',
+      };
+    }
+
+    return {
+      category: 'Disk Space',
+      status: 'healthy',
+      message: `Workspace size: ${sizeStr}`,
+    };
+  } catch (error) {
+    return {
+      category: 'Disk Space',
+      status: 'warning',
+      message: 'Could not calculate disk usage',
+    };
+  }
+};
+
+export const checkMetadataIntegrity = async (
+  workspacePath: string,
+  metadata: WorkspaceMetadata
+): Promise<HealthCheckResult> => {
+  const issues: string[] = [];
+
+  // Check required fields
+  if (!metadata.workspaceName) {
+    issues.push('Missing workspace name');
+  }
+
+  if (!metadata.createdAt) {
+    issues.push('Missing creation timestamp');
+  }
+
+  if (!metadata.repositories || metadata.repositories.length === 0) {
+    issues.push('No repositories in metadata');
+  }
+
+  // Check for duplicate directory names
+  const dirNames = metadata.repositories.map(r => r.directoryName);
+  const uniqueDirNames = new Set(dirNames);
+  if (dirNames.length !== uniqueDirNames.size) {
+    issues.push('Duplicate directory names in metadata');
+  }
+
+  // Check for extra directories not in metadata
+  try {
+    const entries = await fs.readdir(workspacePath, { withFileTypes: true });
+    const directories = entries.filter(e => e.isDirectory()).map(e => e.name);
+    const metadataDirNames = new Set(dirNames);
+    const extraDirs = directories.filter(
+      dir => !metadataDirNames.has(dir) && !dir.startsWith('.')
+    );
+
+    if (extraDirs.length > 0) {
+      issues.push(`${extraDirs.length} directories not tracked in metadata: ${extraDirs.join(', ')}`);
+    }
+  } catch (error) {
+    // Ignore read errors
+  }
+
+  if (issues.length === 0) {
+    return {
+      category: 'Metadata Integrity',
+      status: 'healthy',
+      message: 'Metadata is valid',
+    };
+  }
+
+  return {
+    category: 'Metadata Integrity',
+    status: 'warning',
+    message: 'Metadata issues detected',
+    details: issues.join('\n'),
+    actionable: 'Review workspace metadata file',
+  };
+};
+
+export const checkGhqInstalled = async (): Promise<HealthCheckResult> => {
+  try {
+    await execAsync('which ghq', { timeout: 5000 });
+    return {
+      category: 'ghq',
+      status: 'healthy',
+      message: 'ghq is installed (fast cached clones enabled)',
+    };
+  } catch {
+    return {
+      category: 'ghq',
+      status: 'warning',
+      message: 'ghq is not installed',
+      details: 'Without ghq, repos are cloned directly with git — slower, no shared cache, and large repos can hit clone timeouts.',
+      actionable: 'Install ghq: brew install ghq (macOS) — https://github.com/x-motemen/ghq#installation',
+    };
+  }
+};
+
+export const runAllHealthChecks = async (
+  workspacePath: string,
+  metadata: WorkspaceMetadata
+): Promise<HealthCheckResult[]> => {
+  const repoNames = metadata.repositories.map(r => r.directoryName);
+
+  const checks = await Promise.all([
+    checkMissingRepositories(workspacePath, metadata),
+    checkGitHealth(workspacePath, repoNames),
+    checkUncommittedChanges(workspacePath, repoNames),
+    checkAuthentication(),
+    checkGhqInstalled(),
+    checkDependencies(workspacePath, repoNames),
+    checkDiskSpace(workspacePath),
+    checkMetadataIntegrity(workspacePath, metadata),
+  ]);
+
+  return checks;
+};
+
+export const calculateHealthScore = (results: HealthCheckResult[]): number => {
+  const weights = {
+    healthy: 100,
+    warning: 60,
+    error: 0,
+  };
+
+  const totalWeight = results.reduce((sum, result) => sum + weights[result.status], 0);
+  const maxWeight = results.length * 100;
+
+  return Math.round((totalWeight / maxWeight) * 100);
+};

package/src/utils/history.ts

@@ -0,0 +1,140 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+const CACHE_DIR = path.join(os.homedir(), '.workspace-manager-cache');
+const HISTORY_FILE = path.join(CACHE_DIR, 'history.jsonl');
+
+export interface OperationRecord {
+  timestamp: string;
+  command: string;
+  workspace?: string;
+  duration: number;
+  success: boolean;
+  error?: string;
+}
+
+export const ensureCacheDir = async (): Promise<void> => {
+  try {
+    await fs.mkdir(CACHE_DIR, { recursive: true });
+  } catch {
+    // Ignore if already exists
+  }
+};
+
+export const logOperation = async (record: OperationRecord): Promise<void> => {
+  await ensureCacheDir();
+
+  const line = JSON.stringify(record) + '\n';
+
+  try {
+    await fs.appendFile(HISTORY_FILE, line, 'utf-8');
+  } catch (error) {
+    // Silently fail - don't block operations if logging fails
+  }
+};
+
+export const readHistory = async (limit?: number): Promise<OperationRecord[]> => {
+  try {
+    const content = await fs.readFile(HISTORY_FILE, 'utf-8');
+    const lines = content.trim().split('\n');
+    const records = lines
+      .filter(line => line.trim())
+      .map(line => {
+        try {
+          return JSON.parse(line) as OperationRecord;
+        } catch {
+          return null;
+        }
+      })
+      .filter((record): record is OperationRecord => record !== null);
+
+    // Return most recent first
+    const reversed = records.reverse();
+
+    return limit ? reversed.slice(0, limit) : reversed;
+  } catch {
+    return [];
+  }
+};
+
+export const getOperationStats = async (): Promise<{
+  totalOperations: number;
+  successRate: number;
+  avgDuration: number;
+  commandCounts: Record<string, number>;
+}> => {
+  const history = await readHistory();
+
+  if (history.length === 0) {
+    return {
+      totalOperations: 0,
+      successRate: 0,
+      avgDuration: 0,
+      commandCounts: {},
+    };
+  }
+
+  const successful = history.filter(r => r.success).length;
+  const totalDuration = history.reduce((sum, r) => sum + r.duration, 0);
+  const commandCounts: Record<string, number> = {};
+
+  for (const record of history) {
+    commandCounts[record.command] = (commandCounts[record.command] || 0) + 1;
+  }
+
+  return {
+    totalOperations: history.length,
+    successRate: (successful / history.length) * 100,
+    avgDuration: totalDuration / history.length,
+    commandCounts,
+  };
+};
+
+export const filterHistory = async (
+  command?: string,
+  workspace?: string,
+  successOnly?: boolean
+): Promise<OperationRecord[]> => {
+  const history = await readHistory();
+
+  return history.filter(record => {
+    if (command && record.command !== command) return false;
+    if (workspace && record.workspace !== workspace) return false;
+    if (successOnly && !record.success) return false;
+    return true;
+  });
+};
+
+export const clearHistory = async (): Promise<void> => {
+  try {
+    await fs.unlink(HISTORY_FILE);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+};
+
+export class OperationTimer {
+  private startTime: number;
+  private command: string;
+  private workspace?: string;
+
+  constructor(command: string, workspace?: string) {
+    this.command = command;
+    this.workspace = workspace;
+    this.startTime = Date.now();
+  }
+
+  async end(success: boolean, error?: string): Promise<void> {
+    const duration = Date.now() - this.startTime;
+
+    await logOperation({
+      timestamp: new Date().toISOString(),
+      command: this.command,
+      workspace: this.workspace,
+      duration,
+      success,
+      error,
+    });
+  }
+}

package/src/utils/hooks.ts

@@ -0,0 +1,92 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import { RepositoryMetadata, PostCloneHook } from '../types';
+import { logInfo, logSuccess, logError, logWarning } from './logger';
+import { colorize } from './colors';
+
+const execAsync = promisify(exec);
+
+const HOOK_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+export interface HookResult {
+  repo: string;
+  command: string;
+  status: 'success' | 'failed';
+  error?: string;
+}
+
+export async function runPostCloneHooks(
+  workspacePath: string,
+  repositories: RepositoryMetadata[],
+  hooks?: PostCloneHook[]
+): Promise<HookResult[]> {
+  if (!hooks || hooks.length === 0) {
+    return [];
+  }
+
+  const results: HookResult[] = [];
+
+  logInfo('Running post-clone hooks...');
+  console.log('');
+
+  for (const hook of hooks) {
+    if (hook.description) {
+      logInfo(`Hook: ${colorize(hook.description, 'cyan')}`);
+    }
+
+    // Determine target repos
+    const targetRepos = hook.repoName
+      ? repositories.filter(r => r.name === hook.repoName || r.directoryName === hook.repoName)
+      : repositories;
+
+    if (targetRepos.length === 0) {
+      if (hook.repoName) {
+        logWarning(`No matching repo found for hook target: ${hook.repoName}`);
+      }
+      continue;
+    }
+
+    for (const repo of targetRepos) {
+      const repoPath = path.join(workspacePath, repo.directoryName);
+
+      for (const command of hook.commands) {
+        try {
+          logInfo(`  [${colorize(repo.directoryName, 'cyan')}] ${command}`);
+          await execAsync(command, { cwd: repoPath, timeout: HOOK_TIMEOUT });
+
+          results.push({
+            repo: repo.directoryName,
+            command,
+            status: 'success',
+          });
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+          results.push({
+            repo: repo.directoryName,
+            command,
+            status: 'failed',
+            error: errorMessage,
+          });
+
+          logError(`  [${repo.directoryName}] Failed: ${errorMessage}`);
+
+          if (!hook.continueOnError) {
+            logWarning('Hook execution stopped due to error (continueOnError is false)');
+            return results;
+          }
+        }
+      }
+    }
+  }
+
+  // Log summary
+  const successful = results.filter(r => r.status === 'success').length;
+  const failed = results.filter(r => r.status === 'failed').length;
+
+  console.log('');
+  logInfo(`Hook results: ${colorize(String(successful), 'green')} successful, ${colorize(String(failed), 'red')} failed`);
+
+  return results;
+}

package/src/utils/logger.ts

@@ -0,0 +1,37 @@
+import { colors, colorize } from './colors';
+
+const getTimestamp = (): string => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', {
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit'
+  });
+};
+
+export const logInfo = (message: string): void => {
+  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${message}`);
+};
+
+export const logSuccess = (message: string): void => {
+  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✓', 'green')} ${message}`);
+};
+
+export const logError = (message: string): void => {
+  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✗', 'red')} ${message}`);
+};
+
+export const logWarning = (message: string): void => {
+  console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('⚠', 'yellow')} ${message}`);
+};
+
+export const logStep = (stepOrMessage: number | string, total?: number, message?: string): void => {
+  if (typeof stepOrMessage === 'string') {
+    // Single parameter version: just a message
+    console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('▸', 'cyan')} ${stepOrMessage}`);
+  } else {
+    // Three parameter version: step, total, message
+    console.log(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize(`[${stepOrMessage}/${total}]`, 'cyan')} ${message}`);
+  }
+};