@nemus-cli/nemus 0.2.1

package/src/utils/agent-config.ts

@@ -0,0 +1,264 @@
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { getUserConfig, AgentType, PrimaryAgentType, ConcreteAgentType } from './config';
+
+// Re-export for convenience
+export { AgentType, PrimaryAgentType, ConcreteAgentType } from './config';
+
+export interface AgentPaths {
+  /** Agent identifier */
+  type: ConcreteAgentType;
+  /** Directory for skills (e.g. ~/.claude/skills or ~/.pi/agent/skills) */
+  skillsDir: string;
+  /** Settings file (e.g. ~/.claude/settings.json or ~/.pi/agent/settings.json) */
+  settingsFile: string;
+  /** Context file name generated in workspaces (e.g. CLAUDE.md or AGENTS.md) */
+  contextFileName: string;
+  /** CLI command to launch the agent */
+  launchCommand: string;
+  /** CLI command to resume a session */
+  resumeCommand: (sessionId: string) => string;
+  /** Whether this agent supports MCP (Model Context Protocol) */
+  supportsMcp: boolean;
+  /** Whether this agent supports hooks in settings.json (Claude Code format) */
+  supportsHooks: boolean;
+  /** Session projects directory (for session discovery) */
+  sessionProjectsDir: string;
+}
+
+const HOME = os.homedir();
+
+/**
+ * Detection order for `auto` / `both` / `getPrimaryAgent`. Also the order agents
+ * appear in `getActiveAgents()`. Add a new agent's config below and to this list.
+ */
+export const AGENT_ORDER: ConcreteAgentType[] = ['claude', 'pi', 'opencode', 'codex', 'gemini'];
+
+const CLAUDE_PATHS: AgentPaths = {
+  type: 'claude',
+  skillsDir: path.join(HOME, '.claude', 'skills'),
+  settingsFile: path.join(HOME, '.claude', 'settings.json'),
+  // Must be exactly 'CLAUDE.md': Claude Code only auto-discovers CLAUDE.md /
+  // AGENTS.md up the cwd/ancestor chain. A hidden lowercase '.claude.md' is
+  // invisible to its project-memory loader, so the workspace context (and its
+  // 'Saved Context' pointer) would never surface automatically (issue #186).
+  contextFileName: 'CLAUDE.md',
+  launchCommand: 'claude',
+  resumeCommand: (id: string) => `claude --resume ${id} --fork-session`,
+  supportsMcp: true,
+  supportsHooks: true,
+  sessionProjectsDir: path.join(HOME, '.claude', 'projects'),
+};
+
+const PI_PATHS: AgentPaths = {
+  type: 'pi',
+  skillsDir: path.join(HOME, '.pi', 'agent', 'skills'),
+  settingsFile: path.join(HOME, '.pi', 'agent', 'settings.json'),
+  contextFileName: 'AGENTS.md',
+  launchCommand: 'pi',
+  resumeCommand: (id: string) => `pi --session ${id} --fork`,
+  supportsMcp: false,
+  supportsHooks: false,
+  sessionProjectsDir: path.join(HOME, '.pi', 'agent', 'sessions'),
+};
+
+// OpenCode uses XDG paths: ~/.local/share/opencode for data, ~/.config/opencode for config
+// It reads skills from ~/.claude/skills/ automatically (Claude-compatible)
+// Project config lives in .opencode/ within the project directory
+const OPENCODE_DATA_DIR = path.join(process.env.XDG_DATA_HOME || path.join(HOME, '.local', 'share'), 'opencode');
+const OPENCODE_CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(HOME, '.config'), 'opencode');
+
+const OPENCODE_PATHS: AgentPaths = {
+  type: 'opencode',
+  // OpenCode reads skills from ~/.claude/skills/ natively — no separate install needed
+  skillsDir: path.join(HOME, '.claude', 'skills'),
+  settingsFile: path.join(OPENCODE_CONFIG_DIR, 'opencode.jsonc'),
+  contextFileName: 'AGENTS.md',
+  launchCommand: 'opencode',
+  resumeCommand: (_id: string) => `opencode --continue`,
+  supportsMcp: true,
+  supportsHooks: false,
+  sessionProjectsDir: OPENCODE_DATA_DIR,
+};
+
+// Codex (OpenAI Codex CLI) — config under ~/.codex, reads AGENTS.md for context,
+// supports MCP servers via ~/.codex/config.toml. No native skills or hooks.
+const CODEX_HOME = process.env.CODEX_HOME || path.join(HOME, '.codex');
+const CODEX_PATHS: AgentPaths = {
+  type: 'codex',
+  skillsDir: path.join(CODEX_HOME, 'skills'),
+  settingsFile: path.join(CODEX_HOME, 'config.toml'),
+  contextFileName: 'AGENTS.md',
+  launchCommand: 'codex',
+  resumeCommand: (id: string) => `codex resume ${id}`,
+  supportsMcp: true,
+  supportsHooks: false,
+  sessionProjectsDir: path.join(CODEX_HOME, 'sessions'),
+};
+
+// Gemini (Google Gemini CLI) — config under ~/.gemini, reads GEMINI.md for
+// context, supports MCP servers via ~/.gemini/settings.json. No hooks.
+const GEMINI_HOME = path.join(HOME, '.gemini');
+const GEMINI_PATHS: AgentPaths = {
+  type: 'gemini',
+  skillsDir: path.join(GEMINI_HOME, 'skills'),
+  settingsFile: path.join(GEMINI_HOME, 'settings.json'),
+  contextFileName: 'GEMINI.md',
+  launchCommand: 'gemini',
+  resumeCommand: (_id: string) => `gemini`,
+  supportsMcp: true,
+  supportsHooks: false,
+  sessionProjectsDir: path.join(GEMINI_HOME, 'tmp'),
+};
+
+const AGENT_REGISTRY: Record<ConcreteAgentType, AgentPaths> = {
+  claude: CLAUDE_PATHS,
+  pi: PI_PATHS,
+  opencode: OPENCODE_PATHS,
+  codex: CODEX_PATHS,
+  gemini: GEMINI_PATHS,
+};
+
+/**
+ * Get AgentPaths for a specific agent type.
+ */
+export function getAgentPaths(agent: ConcreteAgentType): AgentPaths {
+  return { ...AGENT_REGISTRY[agent] };
+}
+
+/**
+ * Resolve 'auto' to a concrete agent type by detecting installed CLIs.
+ * Cached after first call to avoid repeated shell exec.
+ */
+let resolvedAutoAgent: ConcreteAgentType | 'both' | null = null;
+
+function resolveAutoAgent(): ConcreteAgentType | 'both' {
+  if (resolvedAutoAgent) return resolvedAutoAgent;
+
+  const available = AGENT_ORDER.filter(a => isAgentCliAvailable(a));
+
+  // If multiple agents detected, use 'both' (meaning: all available agents).
+  if (available.length > 1) resolvedAutoAgent = 'both';
+  else if (available.length === 1) resolvedAutoAgent = available[0];
+  else resolvedAutoAgent = 'claude'; // default to claude even if not installed
+
+  return resolvedAutoAgent;
+}
+
+/**
+ * Get all active agent configurations based on user config.
+ * Resolves 'auto' by detecting installed CLIs. 'both' means every available agent.
+ */
+export function getActiveAgents(): AgentPaths[] {
+  let { aiAgent } = getUserConfig();
+  if (aiAgent === 'auto') aiAgent = resolveAutoAgent();
+
+  if (aiAgent === 'both') {
+    const agents = AGENT_ORDER.filter(a => isAgentCliAvailable(a)).map(a => ({ ...AGENT_REGISTRY[a] }));
+    // Fallback to Claude if nothing detected (shouldn't happen in 'both' mode)
+    return agents.length > 0 ? agents : [{ ...CLAUDE_PATHS }];
+  }
+
+  return [{ ...AGENT_REGISTRY[aiAgent] }];
+}
+
+/**
+ * Get the preferred (primary) agent — the one used for launching, dashboards, etc.
+ * Uses the `primaryAgent` config. When 'auto', picks the first available CLI.
+ */
+export function getPrimaryAgent(): AgentPaths {
+  const { primaryAgent } = getUserConfig();
+
+  if (primaryAgent !== 'auto') return { ...AGENT_REGISTRY[primaryAgent] };
+
+  // 'auto' — pick first available in detection order
+  const first = AGENT_ORDER.find(a => isAgentCliAvailable(a));
+  return { ...AGENT_REGISTRY[first ?? 'claude'] };
+}
+
+/**
+ * Check if a specific agent CLI is available on the system.
+ * Result is cached per agent to avoid repeated execSync overhead.
+ */
+const cliAvailabilityCache = new Map<string, boolean>();
+
+export function isAgentCliAvailable(agent: ConcreteAgentType): boolean {
+  if (cliAvailabilityCache.has(agent)) return cliAvailabilityCache.get(agent)!;
+
+  const command = `${AGENT_REGISTRY[agent].launchCommand} --version`;
+  let available: boolean;
+  try {
+    execSync(command, { stdio: 'pipe' });
+    available = true;
+  } catch {
+    available = false;
+  }
+
+  cliAvailabilityCache.set(agent, available);
+  return available;
+}
+
+/**
+ * Reset all cached values. For use in tests to ensure clean state.
+ * @internal
+ */
+export function resetAgentConfigCache(): void {
+  resolvedAutoAgent = null;
+  cliAvailabilityCache.clear();
+}
+
+/**
+ * Get all skills directories that should be written to.
+ */
+export function getSkillsTargetDirs(): string[] {
+  const dirs = getActiveAgents().map(a => a.skillsDir);
+  return [...new Set(dirs)];
+}
+
+/**
+ * Get all context file names that should be generated in workspaces.
+ * Deduplicates if multiple agents use the same file.
+ */
+export function getContextFileNames(): string[] {
+  const names = getActiveAgents().map(a => a.contextFileName);
+  return [...new Set(names)];
+}
+
+/**
+ * Get all settings files where hooks should be installed.
+ * Only returns agents that support hooks.
+ */
+export function getHookTargetFiles(): string[] {
+  return getActiveAgents()
+    .filter(a => a.supportsHooks)
+    .map(a => a.settingsFile);
+}
+
+/**
+ * Get all agents that support MCP.
+ */
+export function getMcpAgents(): AgentPaths[] {
+  return getActiveAgents().filter(a => a.supportsMcp);
+}
+
+/**
+ * Get every context file name that any known agent can produce, regardless
+ * of which agents are currently configured. Used when scanning repos for
+ * existing context files (e.g. a Pi workspace may contain repos that were
+ * previously set up for Claude Code, and vice-versa).
+ *
+ * Also includes legacy '.claude.md' — the filename generated for Claude before
+ * issue #186 — so repos/workspaces that still contain one are still recognized.
+ */
+export function getAllKnownContextFileNames(): string[] {
+  // Order matters: this is the per-repo scan PRIORITY (findContextFilesInDir
+  // embeds the first existing candidate per directory). AGENTS.md must come
+  // before CLAUDE.md — in dual-agent repos CLAUDE.md is commonly a thin
+  // "@AGENTS.md" shim, so AGENTS.md holds the real content. '.claude.md' is the
+  // legacy output (pre-#186), kept last so any lingering files are still
+  // recognized.
+  const priority = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.claude.md'];
+  const fromAgents = AGENT_ORDER.map(a => AGENT_REGISTRY[a].contextFileName);
+  return [...new Set([...priority, ...fromAgents])];
+}

package/src/utils/agent-state.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// We need to mock the AGENTS_STATE_DIR to use a temp dir for tests
+let tmpDir: string;
+
+vi.mock('../types/dashboard', async () => {
+  const actual = await vi.importActual('../types/dashboard');
+  return {
+    ...actual as any,
+  };
+});
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-state-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+// Helper to write a state file directly
+function writeStateFile(sessionId: string, state: any) {
+  fs.writeFileSync(
+    path.join(tmpDir, `${sessionId}.json`),
+    JSON.stringify(state, null, 2),
+    'utf-8'
+  );
+}
+
+describe('agent-state', () => {
+  it('writeAgentState + readAgentState round-trip', async () => {
+    // Override the module's AGENTS_STATE_DIR
+    vi.doMock('./agent-state', async () => {
+      const mod = await vi.importActual('./agent-state') as any;
+      return {
+        ...mod,
+        AGENTS_STATE_DIR: tmpDir,
+        ensureStateDir: () => fs.mkdirSync(tmpDir, { recursive: true }),
+      };
+    });
+
+    // Direct file-based test instead of mocking
+    const state = {
+      sessionId: 'test-123',
+      workspace: 'my-workspace',
+      workspacePath: '/home/user/workspaces/my-workspace',
+      pid: process.pid, // Use current PID so it's alive
+      status: 'thinking' as const,
+      startedAt: new Date().toISOString(),
+      lastUpdatedAt: new Date().toISOString(),
+    };
+
+    const filePath = path.join(tmpDir, `${state.sessionId}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf-8');
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const read = JSON.parse(content);
+    expect(read.sessionId).toBe('test-123');
+    expect(read.workspace).toBe('my-workspace');
+    expect(read.status).toBe('thinking');
+  });
+
+  it('handles malformed JSON gracefully', () => {
+    fs.writeFileSync(path.join(tmpDir, 'bad.json'), 'not json{{{', 'utf-8');
+
+    // Reading should return null equivalent
+    try {
+      const content = fs.readFileSync(path.join(tmpDir, 'bad.json'), 'utf-8');
+      const parsed = JSON.parse(content);
+      // Should not get here
+      expect(parsed).toBeUndefined();
+    } catch {
+      // Expected — malformed JSON
+      expect(true).toBe(true);
+    }
+  });
+
+  it('state file structure matches AgentState interface', () => {
+    const state = {
+      sessionId: 'sess-abc',
+      workspace: 'test-ws',
+      workspacePath: '/tmp/ws',
+      pid: 12345,
+      status: 'waiting',
+      startedAt: '2026-03-24T00:00:00.000Z',
+      lastUpdatedAt: '2026-03-24T00:01:00.000Z',
+      tmuxPane: 'ws-dashboard:0.1',
+    };
+
+    writeStateFile('sess-abc', state);
+
+    const content = fs.readFileSync(path.join(tmpDir, 'sess-abc.json'), 'utf-8');
+    const read = JSON.parse(content);
+
+    expect(read).toEqual(state);
+    expect(read.sessionId).toBe('sess-abc');
+    expect(read.status).toBe('waiting');
+    expect(read.tmuxPane).toBe('ws-dashboard:0.1');
+  });
+
+  it('filters .json files only', () => {
+    writeStateFile('valid', { sessionId: 'valid', status: 'idle' });
+    fs.writeFileSync(path.join(tmpDir, 'not-json.txt'), 'hello', 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, '.hidden.json'), '{}', 'utf-8');
+
+    const files = fs.readdirSync(tmpDir).filter(f => f.endsWith('.json') && !f.startsWith('.'));
+    expect(files).toEqual(['valid.json']);
+  });
+
+  it('sorts states by workspace then startedAt', () => {
+    const states = [
+      { workspace: 'beta', startedAt: '2026-03-24T02:00:00Z' },
+      { workspace: 'alpha', startedAt: '2026-03-24T01:00:00Z' },
+      { workspace: 'alpha', startedAt: '2026-03-24T00:00:00Z' },
+      { workspace: 'beta', startedAt: '2026-03-24T01:00:00Z' },
+    ];
+
+    states.sort((a, b) => {
+      const wsCmp = a.workspace.localeCompare(b.workspace);
+      if (wsCmp !== 0) return wsCmp;
+      return new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime();
+    });
+
+    expect(states.map(s => `${s.workspace}:${s.startedAt}`)).toEqual([
+      'alpha:2026-03-24T00:00:00Z',
+      'alpha:2026-03-24T01:00:00Z',
+      'beta:2026-03-24T01:00:00Z',
+      'beta:2026-03-24T02:00:00Z',
+    ]);
+  });
+
+  it('rejects invalid session IDs (path traversal protection)', () => {
+    const invalidIds = [
+      '../../etc/passwd',
+      '../secret',
+      'valid/../evil',
+      'a'.repeat(101), // too long
+      'has spaces',
+      'has/slash',
+      '',
+    ];
+    for (const id of invalidIds) {
+      // isValidSessionId is internal, but we can verify that reading returns null
+      // and that writing to these IDs doesn't create files
+      const filePath = path.join(tmpDir, `${id}.json`);
+      expect(fs.existsSync(filePath)).toBe(false);
+    }
+  });
+
+  it('accepts valid session IDs', () => {
+    const validIds = [
+      'abc123',
+      'a1bf93e4-c587-441b-bac8-0c20b6d0cbe4',
+      'dash-1774438882722-6sl23p',
+      'a',
+    ];
+    for (const id of validIds) {
+      // All valid — just check the regex pattern matches
+      expect(/^[a-zA-Z0-9\-]{1,100}$/.test(id)).toBe(true);
+    }
+  });
+});

package/src/utils/agent-state.ts

@@ -0,0 +1,135 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { AgentState, DASHBOARD_DEFAULTS } from '../types/dashboard';
+
+export const AGENTS_STATE_DIR = path.join(os.homedir(), '.workspace-manager', 'agents');
+
+export function ensureStateDir(): void {
+  fs.mkdirSync(AGENTS_STATE_DIR, { recursive: true });
+}
+
+/**
+ * Validate that a session ID is safe to use as a filename.
+ * Allows only alphanumeric characters and hyphens, max 100 chars.
+ */
+function isValidSessionId(id: string): boolean {
+  return typeof id === 'string' && /^[a-zA-Z0-9\-]{1,100}$/.test(id);
+}
+
+/**
+ * Write agent state atomically (write tmp + rename).
+ */
+export function writeAgentState(state: AgentState): void {
+  if (!isValidSessionId(state.sessionId)) return; // reject invalid IDs silently
+  ensureStateDir();
+  const filePath = path.join(AGENTS_STATE_DIR, `${state.sessionId}.json`);
+  const tmpPath = filePath + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+  } catch {
+    // Clean up tmp on failure
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Read a single agent state by session ID.
+ */
+export function readAgentState(sessionId: string): AgentState | null {
+  if (!isValidSessionId(sessionId)) return null;
+  try {
+    const filePath = path.join(AGENTS_STATE_DIR, `${sessionId}.json`);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content) as AgentState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a process is alive by sending signal 0.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read all agent states, check PID liveness, and clean stale entries.
+ * Returns active states sorted by workspace, then startedAt.
+ */
+export function readAllAgentStates(): AgentState[] {
+  ensureStateDir();
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(AGENTS_STATE_DIR);
+  } catch {
+    return [];
+  }
+
+  const now = Date.now();
+  const states: AgentState[] = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json') || entry.startsWith('.')) continue;
+
+    const sessionId = entry.replace('.json', '');
+    const state = readAgentState(sessionId);
+    if (!state) {
+      // Malformed file — remove it
+      try { fs.unlinkSync(path.join(AGENTS_STATE_DIR, entry)); } catch { /* ignore */ }
+      continue;
+    }
+
+    // PID liveness check for non-stopped states
+    // Skip the check if the state was updated very recently (within 10s)
+    // to allow hooks time to update the PID on session resume
+    if (state.status !== 'stopped' && state.pid > 0) {
+      const age = now - new Date(state.lastUpdatedAt).getTime();
+      if (age > 10_000 && !isProcessAlive(state.pid)) {
+        state.status = 'stopped';
+        state.lastUpdatedAt = new Date().toISOString();
+        writeAgentState(state);
+      }
+    }
+
+    // Filter out stale stopped states
+    if (state.status === 'stopped') {
+      const age = now - new Date(state.lastUpdatedAt).getTime();
+      if (age > DASHBOARD_DEFAULTS.staleTtlMs) {
+        try { fs.unlinkSync(path.join(AGENTS_STATE_DIR, entry)); } catch { /* ignore */ }
+        continue;
+      }
+    }
+
+    states.push(state);
+  }
+
+  // Sort by workspace ascending, then startedAt ascending
+  states.sort((a, b) => {
+    const wsCmp = a.workspace.localeCompare(b.workspace);
+    if (wsCmp !== 0) return wsCmp;
+    return new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime();
+  });
+
+  return states;
+}
+
+/**
+ * Remove a single agent state file.
+ */
+export function removeAgentState(sessionId: string): void {
+  if (!isValidSessionId(sessionId)) return;
+  try {
+    fs.unlinkSync(path.join(AGENTS_STATE_DIR, `${sessionId}.json`));
+  } catch {
+    // File doesn't exist — fine
+  }
+}

package/src/utils/banner.ts

@@ -0,0 +1,24 @@
+import { colors } from './colors';
+
+const g = colors.green;
+const d = colors.dim;
+const b = colors.bright;
+const r = colors.reset;
+
+export const BANNER = `
+${d}    ╭──────────────────────────────────────╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
+${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
+${d}    ╰──────────────────────────────────────╯${r}
+`;
+
+export const BANNER_PLAIN = `
+    ╭──────────────────────────────────────╮
+    │  >_  Nemus                           │
+    │       multi-repo workspaces          │
+    ╰──────────────────────────────────────╯
+`;
+
+export const printBanner = (): void => {
+  console.log(BANNER);
+};