@nemus-cli/nemus 0.2.1

package/src/utils/ghq-integration.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockExecAsync = vi.fn();
+vi.mock('child_process', () => ({
+  exec: (...args: unknown[]) => {
+    const callback = args[args.length - 1] as (err: Error | null, result: { stdout: string; stderr: string }) => void;
+    const command = args[0] as string;
+    const opts = args.length === 3 ? args[1] : {};
+    mockExecAsync(command, opts)
+      .then((result: { stdout: string; stderr: string }) => callback(null, result))
+      .catch((err: Error) => callback(err, { stdout: '', stderr: '' }));
+  },
+}));
+
+vi.mock('./logger', () => ({
+  logSuccess: vi.fn(),
+  logError: vi.fn(),
+  logInfo: vi.fn(),
+  logWarning: vi.fn(),
+}));
+
+vi.mock('./colors', () => ({
+  colorize: (text: string) => text,
+}));
+
+import { cloneWithGhq, describeCloneError } from './ghq-integration';
+
+describe('cloneWithGhq', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('uses git clone --local from ghq cache when repo exists', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.resolve({ stdout: '/usr/bin/ghq\n', stderr: '' });
+      if (cmd === 'ghq root') return Promise.resolve({ stdout: '/home/user/ghq\n', stderr: '' });
+      if (cmd.startsWith('test -d')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git clone --local')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git remote set-url')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    const result = await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    expect(result.success).toBe(true);
+    expect(result.usedGhq).toBe(true);
+
+    // Should use git clone --local, not cp -R
+    const calls = mockExecAsync.mock.calls.map(([cmd]: [string]) => cmd);
+    expect(calls.some((cmd: string) => cmd.includes('git clone --local'))).toBe(true);
+    expect(calls.some((cmd: string) => cmd.includes('cp -R'))).toBe(false);
+
+    // Should set remote URL back to original
+    expect(calls.some((cmd: string) => cmd.includes('git remote set-url origin'))).toBe(true);
+  });
+
+  it('does not call ghq get -u when repo is already cached', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.resolve({ stdout: '/usr/bin/ghq\n', stderr: '' });
+      if (cmd === 'ghq root') return Promise.resolve({ stdout: '/home/user/ghq\n', stderr: '' });
+      if (cmd.startsWith('test -d')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git clone --local')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git remote set-url')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    const calls = mockExecAsync.mock.calls.map(([cmd]: [string]) => cmd);
+    // Should NOT call ghq get since repo is cached
+    expect(calls.some((cmd: string) => cmd.startsWith('ghq get'))).toBe(false);
+  });
+
+  it('calls ghq get (without -u) when repo is not cached', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.resolve({ stdout: '/usr/bin/ghq\n', stderr: '' });
+      if (cmd === 'ghq root') return Promise.resolve({ stdout: '/home/user/ghq\n', stderr: '' });
+      if (cmd.startsWith('test -d')) return Promise.reject(new Error('not found'));
+      if (cmd.startsWith('ghq get')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git clone --local')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git remote set-url')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    const calls = mockExecAsync.mock.calls.map(([cmd]: [string]) => cmd);
+    const ghqGetCalls = calls.filter((cmd: string) => cmd.startsWith('ghq get'));
+    expect(ghqGetCalls).toHaveLength(1);
+    // Should NOT use -u flag
+    expect(ghqGetCalls[0]).not.toContain('-u');
+  });
+
+  it('skips local clone and falls back to direct clone when ghq get fails', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.resolve({ stdout: '/usr/bin/ghq\n', stderr: '' });
+      if (cmd === 'ghq root') return Promise.resolve({ stdout: '/home/user/ghq\n', stderr: '' });
+      if (cmd.startsWith('test -d')) return Promise.reject(new Error('not found'));
+      if (cmd.startsWith('ghq get')) return Promise.reject(new Error('network error'));
+      if (cmd.startsWith('git clone')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    const result = await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    expect(result.success).toBe(true);
+    expect(result.usedGhq).toBe(false);
+
+    const calls = mockExecAsync.mock.calls.map(([cmd]: [string]) => cmd);
+    // Should NOT attempt git clone --local since ghq get failed
+    expect(calls.some((cmd: string) => cmd.includes('--local'))).toBe(false);
+    // Should fall back to direct clone
+    expect(calls.some((cmd: string) => cmd.startsWith('git clone "git@github.com'))).toBe(true);
+  });
+
+  it('falls back to direct git clone when ghq is not installed', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.reject(new Error('not found'));
+      if (cmd.startsWith('git clone')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    const result = await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    expect(result.success).toBe(true);
+    expect(result.usedGhq).toBe(false);
+
+    const calls = mockExecAsync.mock.calls.map(([cmd]: [string]) => cmd);
+    expect(calls.some((cmd: string) => cmd.startsWith('git clone "git@github.com'))).toBe(true);
+    expect(calls.some((cmd: string) => cmd.includes('--local'))).toBe(false);
+  });
+
+  it('falls back to direct git clone when local clone fails', async () => {
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (cmd === 'which ghq') return Promise.resolve({ stdout: '/usr/bin/ghq\n', stderr: '' });
+      if (cmd === 'ghq root') return Promise.resolve({ stdout: '/home/user/ghq\n', stderr: '' });
+      if (cmd.startsWith('test -d')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git clone --local')) return Promise.reject(new Error('local clone failed'));
+      if (cmd.startsWith('rm -rf')) return Promise.resolve({ stdout: '', stderr: '' });
+      if (cmd.startsWith('git clone')) return Promise.resolve({ stdout: '', stderr: '' });
+      return Promise.resolve({ stdout: '', stderr: '' });
+    });
+
+    const result = await cloneWithGhq('git@github.com:acme/platform-app.git', '/workspace/platform-app');
+
+    expect(result.success).toBe(true);
+    expect(result.usedGhq).toBe(false);
+  });
+});
+
+describe('describeCloneError', () => {
+  it('explains a timeout (killed + SIGTERM) with actionable fixes', () => {
+    const err = Object.assign(new Error('Command failed: git clone https://…'), {
+      killed: true,
+      signal: 'SIGTERM',
+      stderr: "Cloning into '/x'...",
+    });
+    const msg = describeCloneError(err, 15 * 60 * 1000);
+    expect(msg).toContain('timed out after 15 min');
+    expect(msg).toContain('ghq');
+    expect(msg).toContain('WORKSPACE_CLONE_TIMEOUT_MS');
+  });
+
+  it('explains ETIMEDOUT code as a timeout', () => {
+    const err = Object.assign(new Error('boom'), { code: 'ETIMEDOUT' });
+    expect(describeCloneError(err, 5 * 60 * 1000)).toContain('timed out after 5 min');
+  });
+
+  it('explains a maxBuffer kill', () => {
+    const err = Object.assign(new Error('boom'), { code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' });
+    expect(describeCloneError(err)).toContain('buffer limit');
+  });
+
+  it('classifies a maxBuffer kill as buffer (not timeout) even when killed=true', () => {
+    // Node sets killed=true on maxBuffer kills too; the buffer branch must win.
+    const err = Object.assign(new Error('boom'), {
+      killed: true,
+      signal: 'SIGTERM',
+      code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+    });
+    const msg = describeCloneError(err, 15 * 60 * 1000);
+    expect(msg).toContain('buffer limit');
+    expect(msg).not.toContain('timed out');
+  });
+
+  it('falls back to message + stderr tail for ordinary failures', () => {
+    const err = Object.assign(new Error('fatal: repository not found'), {
+      stderr: 'remote: Repository not found.\nfatal: repository not found',
+    });
+    const msg = describeCloneError(err);
+    expect(msg).toContain('fatal: repository not found');
+    expect(msg).toContain('git:');
+    expect(msg).not.toContain('timed out');
+  });
+});

package/src/utils/ghq-integration.ts

@@ -0,0 +1,317 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import { logInfo, logSuccess, logWarning } from './logger';
+import { colorize } from './colors';
+import { CLONE_TIMEOUT_MS, CLONE_MAX_BUFFER } from './config';
+
+const execAsync = promisify(exec);
+
+/**
+ * Turn a raw child-process clone failure (from exec or execFile) into an
+ * actionable message. The child API discards the reason on timeout/buffer kill (you just get "Command
+ * failed: git clone …"), so we inspect killed/signal/code and the captured
+ * stderr to explain what actually happened and how to fix it.
+ */
+export function describeCloneError(error: unknown, timeoutMs: number = CLONE_TIMEOUT_MS): string {
+  const e = (error ?? {}) as { message?: string; killed?: boolean; signal?: string; code?: string; stderr?: string };
+  const stderr = (e.stderr || '').trim();
+  const tail = stderr ? `\n  git: ${stderr.split('\n').filter(Boolean).slice(-3).join(' ')}` : '';
+
+  // Check maxBuffer FIRST: Node sets killed=true on a maxBuffer kill too, so
+  // the timeout heuristic below would otherwise shadow this case.
+  if (e.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+    return `Clone output exceeded the buffer limit (very large repo). Install ghq (brew install ghq) for cached clones.${tail}`;
+  }
+
+  const timedOut = e.killed === true || e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT';
+  if (timedOut) {
+    const mins = Math.round(timeoutMs / 60000);
+    return `Clone timed out after ${mins} min — the repo may be large or the network slow. `
+      + `Fixes: install ghq for fast cached clones (brew install ghq), switch to SSH (w configure), `
+      + `or raise the limit with WORKSPACE_CLONE_TIMEOUT_MS.${tail}`;
+  }
+  return `${e.message || 'Unknown error'}${tail}`;
+}
+
+/**
+ * Check if ghq is installed
+ */
+export async function isGhqInstalled(): Promise<boolean> {
+  try {
+    await execAsync('which ghq');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify ghq is installed and, if not, warn with install guidance.
+ * ghq gives fast cached clones (shared across workspaces) and avoids the
+ * clone-timeout failures large repos hit over plain git-over-HTTPS.
+ * Returns true if ghq is available. Non-blocking — clones still work without it.
+ */
+export async function warnIfGhqMissing(): Promise<boolean> {
+  if (await isGhqInstalled()) return true;
+  logWarning('ghq is not installed — using direct git clone (slower, no shared cache).');
+  logInfo('  ghq caches repos so re-cloning across workspaces is near-instant and large repos avoid clone timeouts.');
+  logInfo(`  Install: ${colorize('brew install ghq', 'cyan')}  (macOS)  —  Linux/Windows: https://github.com/x-motemen/ghq#installation`);
+  return false;
+}
+
+/**
+ * Get ghq root directory
+ */
+export async function getGhqRoot(): Promise<string | null> {
+  try {
+    const { stdout } = await execAsync('ghq root');
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a repository exists in ghq
+ */
+export async function ghqRepoExists(repoUrl: string): Promise<boolean> {
+  try {
+    const repoPath = await getGhqRepoPath(repoUrl);
+    if (!repoPath) return false;
+
+    await execAsync(`test -d "${repoPath}"`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the local path for a ghq-managed repository
+ */
+export async function getGhqRepoPath(repoUrl: string): Promise<string | null> {
+  try {
+    // Extract org/repo from URL
+    // e.g., git@github.com:my-org/my-app.git -> github.com/my-org/my-app
+    const match = repoUrl.match(/github\.com[:/]([^/]+)\/([^.]+)/);
+    if (!match) return null;
+
+    const [, org, repo] = match;
+    const ghqRoot = await getGhqRoot();
+    if (!ghqRoot) return null;
+
+    return path.join(ghqRoot, 'github.com', org, repo);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clone repository using ghq
+ */
+export async function ghqGet(repoUrl: string): Promise<{ success: boolean; path?: string; error?: string }> {
+  try {
+    logInfo(`Using ghq to clone ${colorize(repoUrl, 'cyan')}...`);
+
+    await execAsync(`ghq get "${repoUrl}"`, { timeout: CLONE_TIMEOUT_MS, maxBuffer: CLONE_MAX_BUFFER });
+
+    const repoPath = await getGhqRepoPath(repoUrl);
+    if (!repoPath) {
+      return { success: false, error: 'Could not determine ghq path' };
+    }
+
+    logSuccess(`Repository available in ghq: ${colorize(repoPath, 'gray')}`);
+
+    return { success: true, path: repoPath };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    return { success: false, error: errorMessage };
+  }
+}
+
+/**
+ * List all repositories managed by ghq
+ */
+export async function ghqList(): Promise<string[]> {
+  try {
+    const { stdout } = await execAsync('ghq list');
+    return stdout.trim().split('\n').filter(line => line.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Display ghq installation instructions
+ */
+export function displayGhqInfo(): void {
+  console.log('\n' + '='.repeat(60));
+  console.log(colorize('About ghq', 'bright'));
+  console.log('='.repeat(60));
+  console.log('\nghq is a tool for managing Git repositories in a structured way.');
+  console.log('The workspace manager can use ghq for better repository organization.\n');
+  console.log('Installation:');
+  console.log('  brew install ghq\n');
+  console.log('Benefits:');
+  console.log('  • Centralized repository cache');
+  console.log('  • Consistent directory structure');
+  console.log('  • Faster subsequent clones');
+  console.log('  • Works alongside workspace isolation\n');
+  console.log('After installing ghq, the workspace manager will automatically use it.');
+  console.log('='.repeat(60) + '\n');
+}
+
+/**
+ * Clone repository with ghq integration
+ * Falls back to direct git clone if ghq is not available
+ */
+export async function cloneWithGhq(
+  repoUrl: string,
+  targetPath: string
+): Promise<{ success: boolean; error?: string; usedGhq: boolean }> {
+  const hasGhq = await isGhqInstalled();
+
+  if (hasGhq) {
+    // Check if repo already exists in ghq cache
+    const ghqPath = await getGhqRepoPath(repoUrl);
+    let ghqReady = !!(ghqPath && await ghqRepoExists(repoUrl));
+
+    if (!ghqReady) {
+      // Not in cache — clone into ghq first (without -u to avoid extra fetch)
+      const ghqResult = await ghqGet(repoUrl);
+      if (ghqResult.success) {
+        ghqReady = true;
+      } else {
+        logWarning(`ghq clone failed: ${ghqResult.error}`);
+      }
+    }
+
+    // Use git clone --local from ghq cache (hardlinks .git/objects — nearly instant)
+    const sourcePath = ghqPath || (await getGhqRepoPath(repoUrl));
+    if (ghqReady && sourcePath) {
+      try {
+        // Refresh the ghq cache BEFORE clone-local so the workspace gets the
+        // latest content. Without this, an old cache (cloned weeks/months ago)
+        // would serve stale state via hardlinks — user would open a workspace
+        // missing dozens of recent commits.
+        try {
+          await execAsync(
+            `git -C "${sourcePath}" fetch origin --quiet --prune`,
+            { timeout: 90 * 1000 },
+          );
+        } catch {
+          // Network failure or no upstream — fall through with stale cache,
+          // we'll log a warning after the local clone if we can't align to HEAD.
+        }
+
+        await execAsync(`git clone --local "${sourcePath}" "${targetPath}"`, { timeout: 60 * 1000 });
+        // Reset remote to point to the original repo URL (not the local ghq path)
+        await execAsync(`git remote set-url origin "${repoUrl}"`, { cwd: targetPath });
+
+        // Make sure the working tree is at origin's default-branch tip.
+        // Robust against:
+        //   - cache having a non-default branch checked out
+        //   - fetch above failing (network blip)
+        //   - refs/remotes/origin/HEAD symref not being set (some git/ghq combos)
+        let alignedToHead = false;
+        let alignError: string | null = null;
+        try {
+          await execAsync(`git fetch origin --quiet`, { cwd: targetPath, timeout: 60 * 1000 });
+
+          // Explicitly set refs/remotes/origin/HEAD by querying the remote.
+          // Without this, symbolic-ref may fail if the local symref wasn’t set.
+          await execAsync(`git remote set-head origin --auto`, { cwd: targetPath, timeout: 30 * 1000 })
+            .catch(() => { /* if this fails the next step might still succeed */ });
+
+          let defaultBranch: string | null = null;
+          try {
+            const headRes = await execAsync(
+              `git symbolic-ref --short refs/remotes/origin/HEAD`,
+              { cwd: targetPath, timeout: 5000 },
+            );
+            defaultBranch = headRes.stdout.trim().replace(/^origin\//, '');
+          } catch {
+            // Fall back to ls-remote query against the actual remote
+            try {
+              const lsRes = await execAsync(
+                `git ls-remote --symref origin HEAD`,
+                { cwd: targetPath, timeout: 30 * 1000 },
+              );
+              const match = lsRes.stdout.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m);
+              if (match) defaultBranch = match[1];
+            } catch { /* fall through to common-name fallback */ }
+          }
+
+          // Final fallback: try common default branches
+          if (!defaultBranch) {
+            for (const candidate of ['main', 'master']) {
+              const exists = await execAsync(
+                `git rev-parse --verify --quiet origin/${candidate}`,
+                { cwd: targetPath, timeout: 5000 },
+              ).then(() => true).catch(() => false);
+              if (exists) { defaultBranch = candidate; break; }
+            }
+          }
+
+          if (!defaultBranch) {
+            throw new Error('could not determine default branch (no origin/HEAD, no main, no master)');
+          }
+
+          await execAsync(`git checkout --quiet "${defaultBranch}"`, { cwd: targetPath, timeout: 10 * 1000 });
+          await execAsync(`git reset --hard --quiet "origin/${defaultBranch}"`, { cwd: targetPath, timeout: 10 * 1000 });
+          alignedToHead = true;
+        } catch (error) {
+          alignError = error instanceof Error ? error.message : String(error);
+        }
+
+        if (!alignedToHead) {
+          // LOUD warning — stale content silently is the worst UX. Surface it.
+          logWarning(`⚠️  Could not align ${repoUrl} to origin/HEAD — workspace may have stale content!`);
+          if (alignError) logWarning(`   reason: ${alignError}`);
+          logWarning(`   manual fix: cd into the repo and run 'git pull --ff-only'`);
+        }
+
+        return { success: true, usedGhq: true };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logWarning(`Local clone from ghq failed: ${errorMessage}`);
+        // Clean up partial clone before fallback
+        try { await execAsync(`rm -rf "${targetPath}"`); } catch { /* ignore */ }
+        // Fall through to direct clone
+      }
+    }
+  }
+
+  // Fallback to direct git clone
+  try {
+    await execAsync(`git clone "${repoUrl}" "${targetPath}"`, { timeout: CLONE_TIMEOUT_MS, maxBuffer: CLONE_MAX_BUFFER });
+    return { success: true, usedGhq: false };
+  } catch (error) {
+    return { success: false, error: describeCloneError(error), usedGhq: false };
+  }
+}
+
+/**
+ * Show ghq status
+ */
+export async function getGhqStatus(): Promise<{
+  installed: boolean;
+  root?: string;
+  repoCount?: number;
+}> {
+  const installed = await isGhqInstalled();
+
+  if (!installed) {
+    return { installed: false };
+  }
+
+  const root = await getGhqRoot();
+  const repos = await ghqList();
+
+  return {
+    installed: true,
+    root: root || undefined,
+    repoCount: repos.length,
+  };
+}