@nemus-cli/nemus 0.2.1

package/src/utils/claude-sessions.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as path from 'path';
+
+// Mock fs/promises before importing the module
+vi.mock('fs/promises', () => ({
+  readdir: vi.fn(),
+  access: vi.fn(),
+  stat: vi.fn(),
+  open: vi.fn(),
+}));
+
+vi.mock('./config', () => ({
+  WORKSPACES_DIR: '/Users/test/workspaces',
+}));
+
+vi.mock('./agent-config', () => ({
+  getActiveAgents: vi.fn().mockReturnValue([
+    { type: 'claude', sessionProjectsDir: '/Users/test/.claude/projects' },
+  ]),
+}));
+
+import * as fs from 'fs/promises';
+import {
+  getWorkspaceSessions,
+  pathToProjectDirName,
+  extractWorkspaceName,
+  relativeTime,
+} from './claude-sessions';
+
+describe('pathToProjectDirName', () => {
+  it('converts absolute path to Claude project dir format', () => {
+    expect(pathToProjectDirName('/Users/test/workspaces')).toBe('-Users-test-workspaces');
+  });
+
+  it('handles paths with multiple segments', () => {
+    expect(pathToProjectDirName('/Users/yotam/Work/workspaces')).toBe('-Users-yotam-Work-workspaces');
+  });
+});
+
+describe('extractWorkspaceName', () => {
+  const prefix = '-Users-test-workspaces';
+
+  it('extracts simple workspace name', () => {
+    expect(extractWorkspaceName('-Users-test-workspaces-my-project', prefix)).toBe('my-project');
+  });
+
+  it('extracts hyphenated workspace name', () => {
+    expect(extractWorkspaceName('-Users-test-workspaces-auto-virtual-card-fix', prefix)).toBe('auto-virtual-card-fix');
+  });
+
+  it('returns null for trailing dash (no workspace name)', () => {
+    expect(extractWorkspaceName('-Users-test-workspaces-', prefix)).toBe(null);
+  });
+
+  it('returns null when projDir equals prefix', () => {
+    // prefix + 1 slices past the dir, giving empty string
+    expect(extractWorkspaceName('-Users-test-workspaces', prefix)).toBe(null);
+  });
+});
+
+describe('pathToProjectDirName (Pi)', () => {
+  it('converts absolute path to Pi session dir format', () => {
+    expect(pathToProjectDirName('/Users/test/workspaces', 'pi')).toBe('--Users-test-workspaces--');
+  });
+
+  it('handles paths with multiple segments', () => {
+    expect(pathToProjectDirName('/Users/yotam/Work/workspaces', 'pi')).toBe('--Users-yotam-Work-workspaces--');
+  });
+});
+
+describe('extractWorkspaceName (Pi)', () => {
+  const prefix = '--Users-test-workspaces--';
+
+  it('extracts simple workspace name', () => {
+    expect(extractWorkspaceName('--Users-test-workspaces-my-project--', prefix, 'pi')).toBe('my-project');
+  });
+
+  it('extracts hyphenated workspace name', () => {
+    expect(extractWorkspaceName('--Users-test-workspaces-auto-virtual-card-fix--', prefix, 'pi')).toBe('auto-virtual-card-fix');
+  });
+
+  it('returns null for empty workspace name', () => {
+    expect(extractWorkspaceName('--Users-test-workspaces--', prefix, 'pi')).toBe(null);
+  });
+
+  it('returns null for malformed dir without trailing --', () => {
+    expect(extractWorkspaceName('--Users-test-workspaces-my-project', prefix, 'pi')).toBe(null);
+  });
+
+  it('extracts single-char workspace name', () => {
+    expect(extractWorkspaceName('--Users-test-workspaces-x--', prefix, 'pi')).toBe('x');
+  });
+});
+
+describe('relativeTime', () => {
+  it('returns "just now" for times less than a minute ago', () => {
+    expect(relativeTime(new Date(Date.now() - 30_000))).toBe('just now');
+  });
+
+  it('returns minutes for times less than an hour ago', () => {
+    expect(relativeTime(new Date(Date.now() - 5 * 60_000))).toBe('5m ago');
+  });
+
+  it('returns hours for times less than a day ago', () => {
+    expect(relativeTime(new Date(Date.now() - 3 * 3600_000))).toBe('3h ago');
+  });
+
+  it('returns days for times less than a month ago', () => {
+    expect(relativeTime(new Date(Date.now() - 7 * 86400_000))).toBe('7d ago');
+  });
+
+  it('returns months for times more than 30 days ago', () => {
+    expect(relativeTime(new Date(Date.now() - 60 * 86400_000))).toBe('2mo ago');
+  });
+});
+
+describe('getWorkspaceSessions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns empty array when claude projects dir does not exist', async () => {
+    vi.mocked(fs.readdir).mockRejectedValueOnce(new Error('ENOENT'));
+
+    const sessions = await getWorkspaceSessions();
+    expect(sessions).toEqual([]);
+  });
+
+  it('returns empty array when no workspace project dirs exist', async () => {
+    vi.mocked(fs.readdir).mockResolvedValueOnce([
+      '-Users-test-other-project' as any,
+      '-Users-test-standalone' as any,
+    ]);
+
+    const sessions = await getWorkspaceSessions();
+    expect(sessions).toEqual([]);
+  });
+
+  it('skips workspaces that no longer exist on disk', async () => {
+    // Projects dir listing
+    vi.mocked(fs.readdir).mockResolvedValueOnce([
+      '-Users-test-workspaces-deleted-workspace' as any,
+    ]);
+
+    // Workspace does not exist on disk
+    vi.mocked(fs.access).mockRejectedValueOnce(new Error('ENOENT'));
+
+    const sessions = await getWorkspaceSessions();
+    expect(sessions).toEqual([]);
+  });
+
+  it('returns sessions sorted by last active time', async () => {
+    const now = Date.now();
+
+    // Projects dir listing - two workspace project dirs
+    vi.mocked(fs.readdir)
+      .mockResolvedValueOnce([
+        '-Users-test-workspaces-workspace-a' as any,
+        '-Users-test-workspaces-workspace-b' as any,
+      ])
+      // workspace-a session files
+      .mockResolvedValueOnce([
+        'session-a.jsonl' as any,
+      ])
+      // workspace-b session files
+      .mockResolvedValueOnce([
+        'session-b.jsonl' as any,
+      ]);
+
+    // Both workspaces exist
+    vi.mocked(fs.access).mockResolvedValue(undefined);
+
+    // File stats - workspace-b is newer
+    const olderTime = new Date(now - 3600_000); // 1 hour ago
+    const newerTime = new Date(now - 60_000); // 1 minute ago
+
+    vi.mocked(fs.stat)
+      .mockResolvedValueOnce({ mtime: olderTime } as any)
+      .mockResolvedValueOnce({ mtime: newerTime } as any);
+
+    // Mock file open/read for timestamp extraction
+    const mockHandleA = {
+      stat: vi.fn().mockResolvedValue({ size: 100 }),
+      read: vi.fn().mockImplementation((buffer: Buffer) => {
+        const content = JSON.stringify({ timestamp: olderTime.toISOString() }) + '\n';
+        buffer.write(content);
+        return Promise.resolve({ bytesRead: content.length });
+      }),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+    const mockHandleB = {
+      stat: vi.fn().mockResolvedValue({ size: 100 }),
+      read: vi.fn().mockImplementation((buffer: Buffer) => {
+        const content = JSON.stringify({ timestamp: newerTime.toISOString() }) + '\n';
+        buffer.write(content);
+        return Promise.resolve({ bytesRead: content.length });
+      }),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+
+    vi.mocked(fs.open)
+      .mockResolvedValueOnce(mockHandleA as any)
+      .mockResolvedValueOnce(mockHandleB as any);
+
+    const sessions = await getWorkspaceSessions();
+
+    expect(sessions).toHaveLength(2);
+    // Most recent first
+    expect(sessions[0].workspaceName).toBe('workspace-b');
+    expect(sessions[1].workspaceName).toBe('workspace-a');
+  });
+
+  it('skips project dirs with no jsonl files', async () => {
+    vi.mocked(fs.readdir)
+      .mockResolvedValueOnce([
+        '-Users-test-workspaces-empty-workspace' as any,
+      ])
+      // No jsonl files in the project dir
+      .mockResolvedValueOnce([
+        'some-uuid' as any, // directory, not a jsonl file
+      ]);
+
+    vi.mocked(fs.access).mockResolvedValue(undefined);
+
+    const sessions = await getWorkspaceSessions();
+    expect(sessions).toEqual([]);
+  });
+
+  it('falls back to mtime when jsonl has no timestamp', async () => {
+    const mtime = new Date(Date.now() - 7200_000); // 2 hours ago
+
+    vi.mocked(fs.readdir)
+      .mockResolvedValueOnce([
+        '-Users-test-workspaces-fallback-ws' as any,
+      ])
+      .mockResolvedValueOnce([
+        'session-1.jsonl' as any,
+      ]);
+
+    vi.mocked(fs.access).mockResolvedValue(undefined);
+    vi.mocked(fs.stat).mockResolvedValueOnce({ mtime } as any);
+
+    // File open fails - no timestamp extractable
+    vi.mocked(fs.open).mockRejectedValueOnce(new Error('read error'));
+
+    const sessions = await getWorkspaceSessions();
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].workspaceName).toBe('fallback-ws');
+    expect(sessions[0].lastActiveAt).toEqual(mtime);
+  });
+
+  it('excludes the workspaces root dir itself', async () => {
+    // The prefix dir itself should not match
+    vi.mocked(fs.readdir).mockResolvedValueOnce([
+      '-Users-test-workspaces' as any, // This is the root, not a workspace
+    ]);
+
+    const sessions = await getWorkspaceSessions();
+    expect(sessions).toEqual([]);
+  });
+});

package/src/utils/claude-sessions.ts

@@ -0,0 +1,251 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { WORKSPACES_DIR } from './config';
+import { getActiveAgents, AgentPaths, ConcreteAgentType } from './agent-config';
+
+export interface WorkspaceSession {
+  workspaceName: string;
+  workspacePath: string;
+  sessionId: string;
+  lastActiveAt: Date;
+  /** Human-readable relative time, e.g. "2 hours ago" */
+  lastActiveLabel: string;
+  /** Which agent created this session */
+  agentType: ConcreteAgentType;
+}
+
+/**
+ * Scan session directories for workspace-related session files.
+ * Checks Claude (~/.claude/projects/) and/or Pi (~/.pi/agent/sessions/) based on config.
+ * Returns sessions sorted by last activity (most recent first).
+ *
+ * Note: Pi session discovery has limitations. Pi uses a different naming convention
+ * (--path--with--dashes--) vs Claude's (-path-with-dashes). This scanner currently
+ * only reliably finds Claude sessions. Pi session discovery may require updates
+ * based on Pi's actual session directory structure.
+ */
+export async function getWorkspaceSessions(): Promise<WorkspaceSession[]> {
+  const agents = getActiveAgents();
+  const allSessions: WorkspaceSession[] = [];
+
+  // Scan each active agent's session directory
+  for (const agent of agents) {
+    const sessions = await scanProjectsDir(agent.sessionProjectsDir, agent.type);
+    allSessions.push(...sessions);
+  }
+
+  // Deduplicate by workspace + session ID, sort by most recent
+  const seen = new Set<string>();
+  const deduped = allSessions.filter(s => {
+    const key = `${s.workspacePath}:${s.sessionId}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  deduped.sort((a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime());
+  return deduped;
+}
+
+/**
+ * Scan a single projects/sessions directory for workspace sessions.
+ */
+async function scanProjectsDir(projectsDir: string, agentType: ConcreteAgentType): Promise<WorkspaceSession[]> {
+  // Only Claude Code and Pi expose a scannable per-project session directory
+  // layout. OpenCode stores sessions in SQLite; Codex/Gemini use their own
+  // formats that aren't scanned here — skip them.
+  if (agentType !== 'claude' && agentType !== 'pi') return [];
+
+  const workspacesPrefix = pathToProjectDirName(WORKSPACES_DIR, agentType);
+
+  let projectDirs: string[];
+  try {
+    projectDirs = await fs.readdir(projectsDir);
+  } catch {
+    return [];
+  }
+
+  // Filter to only workspace project directories
+  const workspaceProjectDirs = projectDirs.filter(dir => {
+    if (agentType === 'pi') {
+      // Pi dirs: "--{base}-{name}--", so strip trailing -- from prefix to match base + '-'
+      const prefixBase = workspacesPrefix.slice(0, -2); // remove trailing --
+      return dir.startsWith(prefixBase + '-') && dir !== workspacesPrefix;
+    }
+    // Claude: prefix + dash separator
+    return dir.startsWith(workspacesPrefix + '-') && dir !== workspacesPrefix;
+  });
+
+  const sessions: WorkspaceSession[] = [];
+
+  await Promise.all(workspaceProjectDirs.map(async (projDir) => {
+    const workspaceName = extractWorkspaceName(projDir, workspacesPrefix, agentType);
+    if (!workspaceName) return;
+
+    const workspacePath = path.join(WORKSPACES_DIR, workspaceName);
+
+    // Check workspace still exists on disk
+    try {
+      await fs.access(workspacePath);
+    } catch {
+      return; // Workspace deleted, skip
+    }
+
+    const fullProjDir = path.join(projectsDir, projDir);
+    const session = await getMostRecentSession(fullProjDir);
+    if (!session) return;
+
+    sessions.push({
+      workspaceName,
+      workspacePath,
+      sessionId: session.sessionId,
+      lastActiveAt: session.lastActiveAt,
+      lastActiveLabel: relativeTime(session.lastActiveAt),
+      agentType,
+    });
+  }));
+
+  // Sort by most recently active first
+  sessions.sort((a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime());
+
+  return sessions;
+}
+
+/** @internal exported for testing */
+export function pathToProjectDirName(absPath: string, agentType: 'claude' | 'pi' = 'claude'): string {
+  if (agentType === 'pi') {
+    // Pi format: --Users-yotambloom-Work-workspaces-- (leading --, single - between segments, trailing --)
+    // Strip leading /, then replace remaining / with -
+    const inner = absPath.replace(/^\//, '').replace(/\//g, '-');
+    return '--' + inner + '--';
+  }
+  // Claude format: -Users-yotambloom-Work-workspaces (/ replaced by -)
+  return absPath.replace(/\//g, '-');
+}
+
+/** @internal exported for testing */
+export function extractWorkspaceName(projDir: string, prefix: string, agentType: 'claude' | 'pi' = 'claude'): string | null {
+  if (agentType === 'pi') {
+    // Pi: prefix is "--Users-...-workspaces--", dir is "--Users-...-workspaces-{name}--"
+    // The prefix ends with --, but workspace name is between prefix (minus trailing --) + - and trailing --
+    const prefixBase = prefix.slice(0, -2); // remove trailing --
+    if (!projDir.startsWith(prefixBase + '-')) return null;
+    // Ensure dir is longer than just prefixBase + '--' (which would be the prefix itself)
+    if (projDir === prefix) return null;
+    const rest = projDir.slice(prefixBase.length + 1); // skip the - separator
+    // rest should be "{workspace-name}--" — reject malformed dirs that don't end with --
+    if (!rest.endsWith('--')) return null;
+    const name = rest.slice(0, -2);
+    return name || null;
+  }
+  // Claude: remove prefix + the separator dash
+  const rest = projDir.slice(prefix.length + 1);
+  if (!rest) return null;
+  return rest;
+}
+
+interface SessionInfo {
+  sessionId: string;
+  lastActiveAt: Date;
+}
+
+/**
+ * Find the most recently active session in a project directory.
+ * Reads .jsonl files and checks the last line's timestamp.
+ */
+async function getMostRecentSession(projDir: string): Promise<SessionInfo | null> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(projDir);
+  } catch {
+    return null;
+  }
+
+  const jsonlFiles = entries.filter(f => f.endsWith('.jsonl'));
+  if (jsonlFiles.length === 0) return null;
+
+  let bestSession: SessionInfo | null = null;
+
+  // For performance, check file modification times first to find candidates
+  const fileStats = await Promise.all(
+    jsonlFiles.map(async (f) => {
+      try {
+        const stat = await fs.stat(path.join(projDir, f));
+        return { file: f, mtime: stat.mtime };
+      } catch {
+        return null;
+      }
+    })
+  );
+
+  // Sort by mtime descending, only check the most recent files
+  const sorted = fileStats
+    .filter((s): s is NonNullable<typeof s> => s !== null)
+    .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+
+  // Only read the most recent session file to get accurate timestamp
+  for (const { file, mtime } of sorted.slice(0, 1)) {
+    const sessionId = file.replace('.jsonl', '');
+    const timestamp = await getLastTimestamp(path.join(projDir, file));
+    bestSession = {
+      sessionId,
+      lastActiveAt: timestamp || mtime,
+    };
+  }
+
+  return bestSession;
+}
+
+/**
+ * Read the last few lines of a .jsonl file and extract the most recent timestamp.
+ */
+async function getLastTimestamp(filePath: string): Promise<Date | null> {
+  try {
+    const handle = await fs.open(filePath, 'r');
+    try {
+      const stat = await handle.stat();
+      // Read last 4KB to find the last line with a timestamp
+      const readSize = Math.min(4096, stat.size);
+      const buffer = Buffer.alloc(readSize);
+      await handle.read(buffer, 0, readSize, Math.max(0, stat.size - readSize));
+      const content = buffer.toString('utf-8');
+
+      // Find the last line with a timestamp
+      const lines = content.split('\n').filter(l => l.trim());
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const parsed = JSON.parse(lines[i]);
+          if (parsed.timestamp) {
+            return new Date(parsed.timestamp);
+          }
+        } catch {
+          continue;
+        }
+      }
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/** @internal exported for testing */
+export function relativeTime(date: Date): string {
+  const now = Date.now();
+  const diff = now - date.getTime();
+
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+
+  const months = Math.floor(days / 30);
+  return `${months}mo ago`;
+}

package/src/utils/cleanup-operations.ts

@@ -0,0 +1,94 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const execAsync = promisify(exec);
+
+export interface CleanupResult {
+  operation: string;
+  filesRemoved: number;
+  spaceFreed: string;
+  success: boolean;
+}
+
+export const calculateDirSize = async (dirPath: string): Promise<number> => {
+  try {
+    const { stdout } = await execAsync(`du -sk "${dirPath}"`);
+    const sizeInKB = parseInt(stdout.split('\t')[0], 10);
+    return sizeInKB;
+  } catch {
+    return 0;
+  }
+};
+
+export const removeNodeModules = async (repoPath: string): Promise<CleanupResult> => {
+  const nodeModulesPath = path.join(repoPath, 'node_modules');
+
+  try {
+    const sizeBefore = await calculateDirSize(nodeModulesPath);
+    await fs.rm(nodeModulesPath, { recursive: true, force: true });
+
+    return {
+      operation: 'Remove node_modules',
+      filesRemoved: 1,
+      spaceFreed: `${(sizeBefore / 1024).toFixed(2)} MB`,
+      success: true,
+    };
+  } catch (error) {
+    return {
+      operation: 'Remove node_modules',
+      filesRemoved: 0,
+      spaceFreed: '0 MB',
+      success: false,
+    };
+  }
+};
+
+export const removeBuildArtifacts = async (repoPath: string): Promise<CleanupResult> => {
+  const artifacts = ['dist', 'build', '.next', 'coverage', 'out'];
+  let totalSize = 0;
+  let removed = 0;
+
+  for (const artifact of artifacts) {
+    const artifactPath = path.join(repoPath, artifact);
+    try {
+      const size = await calculateDirSize(artifactPath);
+      await fs.rm(artifactPath, { recursive: true, force: true });
+      totalSize += size;
+      removed++;
+    } catch {
+      // Ignore if doesn't exist
+    }
+  }
+
+  return {
+    operation: 'Remove build artifacts',
+    filesRemoved: removed,
+    spaceFreed: `${(totalSize / 1024).toFixed(2)} MB`,
+    success: true,
+  };
+};
+
+export const gitClean = async (repoPath: string, dryRun: boolean = false): Promise<CleanupResult> => {
+  try {
+    const cmd = dryRun ? 'git clean -fdxn' : 'git clean -fdx';
+    const { stdout } = await execAsync(cmd, { cwd: repoPath });
+
+    const lines = stdout.split('\n').filter(l => l.trim());
+
+    return {
+      operation: 'Git clean',
+      filesRemoved: lines.length,
+      spaceFreed: 'Unknown',
+      success: true,
+    };
+  } catch {
+    return {
+      operation: 'Git clean',
+      filesRemoved: 0,
+      spaceFreed: '0 MB',
+      success: false,
+    };
+  }
+};

package/src/utils/colors.ts

@@ -0,0 +1,25 @@
+export const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+
+  // Foreground colors
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+
+  // Background colors
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+};
+
+export const colorize = (text: string, color: keyof typeof colors): string => {
+  return `${colors[color]}${text}${colors.reset}`;
+};

package/src/utils/command-helpers.ts

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import { listWorkspaces } from './workspace-meta';
+import { promptWorkspaceSelection } from './prompts';
+
+export interface GlobalOpts {
+  forceRefresh: boolean;
+  yes: boolean;
+}
+
+/**
+ * Extract global options (--force-refresh, --yes) from the root program.
+ * Commander doesn't auto-inherit parent options to subcommands,
+ * so we walk up the parent chain to find them.
+ */
+export function getGlobalOpts(cmd: Command): GlobalOpts {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  const opts = root.opts();
+  return {
+    forceRefresh: opts.forceRefresh ?? false,
+    yes: opts.yes ?? false,
+  };
+}
+
+/**
+ * Resolve workspace name: use provided value, or prompt interactively.
+ * In non-interactive mode (no TTY), throws if no name provided.
+ */
+export async function resolveWorkspace(name?: string): Promise<string> {
+  if (name) return name;
+  if (!process.stdout.isTTY) {
+    throw new Error('Workspace name required in non-interactive mode. Use --workspace <name> or provide as argument.');
+  }
+  const workspaces = await listWorkspaces();
+  if (workspaces.length === 0) {
+    throw new Error('No workspaces found. Create one first with: nemus create');
+  }
+  return promptWorkspaceSelection(workspaces);
+}
+
+/**
+ * Parse comma-separated list from a flag value.
+ */
+export function parseList(value: string): string[] {
+  return value.split(',').map(s => s.trim()).filter(Boolean);
+}